@valbuild/core 0.102.0 → 0.103.0

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

@@ -8,18 +8,18 @@ export type { ImageMetadata } from "./schema/image.js";
 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 { FileSource } from "./source/media.js";
 export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
-export type { RemoteSource, RemoteRef } from "./source/remote.js";
+export type { RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
-export type { ImageSource } from "./source/image.js";
+export type { ImageSource } from "./source/media.js";
+export type { MediaHotspot, MediaSource, GalleryImageSource, GalleryFileSource, } from "./source/media.js";
 export type { AllRichTextOptions, Bold, Styles, HeadingNode, ImageNode, Italic, LineThrough, ListItemNode, LinkNode, OrderedListNode, ParagraphNode, BrNode, RichTextNode, RichTextOptions, SerializedRichTextOptions, RichTextSource, BlockNode, SpanNode, UnorderedListNode, } from "./source/richtext.js";
 export { type Val, type SerializedVal, type ModuleFilePath, type PatchId, type ModulePath, type SourcePath, type JsonOfSource, type ParentPatchId, } from "./val/index.js";
 export type { Json, JsonPrimitive, JsonArray, JsonObject } from "./Json.js";
 export type { ValidationError, ValidationErrors, } from "./schema/validation/ValidationError.js";
 export type { ValidationFix } from "./schema/validation/ValidationFix.js";
-export { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG } from "./source/file.js";
 export { VAL_EXTENSION, type SourceArray } from "./source/index.js";
 export { derefPatch } from "./patch/deref.js";
 export { type SelectorSource, type SelectorOf, GenericSelector, } from "./selector/index.js";
@@ -28,20 +28,18 @@ declare const ModuleFilePathSep = "?p=";
 export { ModuleFilePathSep };
 import { SelectorSource, getSchema } from "./selector/index.js";
 import { ModulePath, SourcePath, getValPath, isVal } from "./val/index.js";
-import { convertFileSource } from "./schema/file.js";
 import { createValPathOfItem } from "./selector/SelectorProxy.js";
 import { Operation } from "./patch/index.js";
 import { initSchema } from "./initSchema.js";
 import { getMimeType, mimeTypeToFileExt, filenameToMimeType } from "./mimeType/index.js";
 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";
 import { splitRemoteRef } from "./remote/splitRemoteRef.js";
-import { convertRemoteSource } from "./schema/remote.js";
+import { fillFromGallery, isRemoteMediaPath, mediaUrl, resolveMedia } from "./source/media.js";
 import { colorToHex, convertColor, detectColorFormat, formatColor, parseColor } from "./schema/colorFormat.js";
 export { type SerializedArraySchema, ArraySchema } from "./schema/array.js";
 export { type SerializedObjectSchema, ObjectSchema } from "./schema/object.js";
@@ -72,8 +70,12 @@ declare const Internal: {
     VERSION: {
         core: string | null;
     };
-    convertFileSource: typeof convertFileSource;
-    convertRemoteSource: typeof convertRemoteSource;
+    mediaUrl: typeof mediaUrl;
+    resolveMedia: typeof resolveMedia;
+    isRemoteMediaPath: typeof isRemoteMediaPath;
+    media: {
+        fillFromGallery: typeof fillFromGallery;
+    };
     getSchema: typeof getSchema;
     getValPath: typeof getValPath;
     getSource: typeof getSource;
@@ -100,7 +102,6 @@ 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;

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

@@ -99,19 +99,28 @@ export type InitSchema = {
     /**
      * Define an image.
      *
-     * Use c.image to create an image source.
+     * An image is an object with a `path`. `width`, `height` and `mimeType` are
+     * read from the file — the VS Code extension fills them in as you type the
+     * path, and `npx val validate --fix` adds any that are missing. `alt` and
+     * `hotspot` are yours to set.
      *
      * @example
      * const schema = s.image();
-     * export default c.define("/example.val.ts", schema, c.image("/public/val/example.png", {
-     *  width: 100,
-     *  height: 100,
-     *  mimeType: "image/png",
-     *  hotspot: {
-     *    x: 0.5,
-     *    y: 0.5
-     *  }
-     * }));
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     *   alt: "An example",
+     *   hotspot: { x: 0.5, y: 0.5 },
+     * });
+     *
+     * @example
+     * // Backed by a gallery: width, height and mimeType live there.
+     * const schema = s.image(galleryVal);
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     * });
      *
      */
     readonly image: typeof image;
@@ -146,11 +155,15 @@ export type InitSchema = {
     /**
      * Define a file.
      *
-     * Use `c.file` to create a file source.
+     * A file is an object with a `path`. `mimeType` comes from the extension —
+     * `npx val validate --fix` adds it.
      *
      * @example
      * const schema = s.file();
-     * export default c.define("/example.val.ts", schema, c.file("/public/val/example.png"));
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
      *
      */
     readonly file: typeof file;
@@ -291,11 +304,11 @@ export declare function initSchema(): {
     }) => import("./schema/number.js").NumberSchema<number>;
     union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./schema/union.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
     richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./schema/richtext.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
-    image: (options?: import("./schema/image.js").ImageOptions | import("./module.js").ValModule<Record<string, import("./schema/images.js").ImagesEntryMetadata>>) => import("./schema/image.js").ImageSchema<import("./index.js").ImageSource | import("./index.js").RemoteSource<import("./schema/image.js").ImageMetadata | undefined>>;
+    image: typeof image;
     literal: <T extends string>(value: T) => import("./schema/literal.js").LiteralSchema<T>;
     keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./schema/keyOf.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./schema/string.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./schema/string.js").RawString : never : never>;
     record: typeof record;
-    file: (options?: import("./schema/file.js").FileOptions | import("./module.js").ValModule<Record<string, import("./schema/files.js").FilesEntryMetadata>>) => import("./schema/file.js").FileSchema<import("./index.js").FileSource | import("./index.js").RemoteSource<import("./schema/file.js").FileMetadata | undefined>>;
+    file: typeof file;
     files: (options: import("./schema/files.js").FilesOptions) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
         mimeType: import("./schema/string.js").StringSchema<string>;
     }, {

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

@@ -1,15 +1,9 @@
 import { define } from "./module.js";
 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 = {

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

@@ -4,22 +4,19 @@ import { Source } from "./source/index.js";
 import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
-import { ImageSelector } from "./selector/image.js";
-import { ImageSource } from "./source/image.js";
 declare const brand: unique symbol;
 export type ValModule<T extends SelectorSource> = SelectorOf<T> & ValModuleBrand;
 export type ValModuleBrand = {
     [brand]: "ValModule";
 };
 export type InferValModuleType<T extends ValModule<SelectorSource>> = T extends GenericSelector<infer S> ? S : never;
-export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSource extends T ? T : T extends RawString ? string : T extends ImageSelector ? ImageSource : T extends {
+export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSource extends T ? T : T extends RawString ? string : T extends {
     [key in string]: SelectorSource;
 } ? {
     [key in keyof T]: ReplaceRawStringWithString<T[key]>;
 } : T extends SelectorSource[] ? ReplaceRawStringWithString<T[number]>[] : T;
 export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
 schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
-export declare function enrichFileImageRemoteSourceWithMetadata<T extends SelectorSource>(source: T, schema: Schema<SelectorSource>): T;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
 export declare function splitModuleFilePathAndModulePath(path: SourcePath | ModuleFilePath): [moduleId: ModuleFilePath, path: ModulePath];
 export declare function joinModuleFilePathAndModulePath(moduleFilePath: ModuleFilePath, modulePath: ModulePath): SourcePath;

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

@@ -1,8 +1,6 @@
 import { Schema } from "./schema/index.js";
-import { ImageMetadata } from "./schema/image.js";
 import { SelectorSource } from "./selector/index.js";
-import { ImageSource } from "./source/image.js";
-import { RemoteSource } from "./source/remote.js";
+import { ImageSource } from "./source/media.js";
 import { ModuleFilePath, SourcePath } from "./val/index.js";
 export type ListRecordRender = {
     layout: "list";
@@ -12,7 +10,7 @@ export type ListRecordRender = {
         value: {
             title: string;
             subtitle?: string | null;
-            image?: ImageSource | RemoteSource<ImageMetadata> | null;
+            image?: ImageSource | null;
         }
     ][];
 };
@@ -35,7 +33,7 @@ export type ListArrayRender = {
         value: {
             title: string;
             subtitle?: string | null;
-            image?: ImageSource | RemoteSource<ImageMetadata> | null;
+            image?: ImageSource | null;
         }
     ][];
 };

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

@@ -1,7 +1,7 @@
 import { Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
 import { RenderSelector, ReifiedRender, RenderScope } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
-import { ImageSource } from "../source/image.js";
+import { ImageSource } from "../source/media.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedArraySchema = {

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

@@ -1,9 +1,9 @@
-import { Json } from "../Json.js";
-import { FileSource } from "../source/file.js";
+import { FileSource, GalleryFileSource } from "../source/media.js";
+export type { FileMetadata } from "../source/file.js";
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-import { RemoteSource, ValModule } from "../index.js";
+import { ValModule } from "../index.js";
 import { ReifiedRender } from "../render.js";
 import { FilesEntryMetadata } from "./files.js";
 export type FileOptions = {
@@ -20,10 +20,7 @@ export type SerializedFileSchema = {
     hidden?: boolean;
     description?: string;
 };
-export type FileMetadata = {
-    mimeType?: string;
-};
-export declare class FileSchema<Src extends FileSource<FileMetadata | undefined> | RemoteSource<FileMetadata | undefined> | null> extends Schema<Src> {
+export declare class FileSchema<Src extends FileSource | null> extends Schema<Src> {
     private readonly options?;
     private readonly opt;
     protected readonly isRemote: boolean;
@@ -34,9 +31,14 @@ export declare class FileSchema<Src extends FileSource<FileMetadata | undefined>
     private readonly description?;
     constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     describe(description: string | null): FileSchema<Src>;
-    remote(): FileSchema<Src | RemoteSource<FileMetadata | undefined>>;
+    remote(): FileSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): FileSchema<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(): FileSchema<Src | null>;
     readonly(): FileSchema<Src>;
@@ -45,12 +47,10 @@ export declare class FileSchema<Src extends FileSource<FileMetadata | undefined>
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }
-export declare const file: (options?: FileOptions | ValModule<Record<string, FilesEntryMetadata>>) => FileSchema<FileSource | RemoteSource<FileMetadata | undefined>>;
-export declare function convertFileSource<Metadata extends {
-    readonly [key: string]: Json;
-} | undefined = {
-    readonly [key: string]: Json;
-} | undefined>(src: FileSource<Metadata>): {
-    url: string;
-    metadata?: Metadata;
-};
+/**
+ * A file picked from a gallery. Its mime type lives in the gallery, so the
+ * field carries only the path.
+ */
+export declare function file(galleryModule: ValModule<Record<string, FilesEntryMetadata>>): FileSchema<GalleryFileSource>;
+/** A file of its own, carrying its own mime type. */
+export declare function file(options?: FileOptions): FileSchema<FileSource>;

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

@@ -1,10 +1,8 @@
 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 { ImagesEntryMetadata } from "./images.js";
 export type ImageOptions = {
@@ -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,9 +43,14 @@ 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>;
@@ -56,4 +59,10 @@ export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefine
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }
-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,7 +17,7 @@ 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";
 export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;

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

@@ -2,11 +2,9 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, S
 import { RenderSelector, ReifiedRender, RenderScope } from "../render.js";
 import { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
-import { ImageSource } from "../source/image.js";
+import { ImageSource } from "../source/media.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";
@@ -56,7 +54,7 @@ type RecordRenderInput<T extends Schema<SelectorSource>> = {
     }) => {
         title: string;
         subtitle?: string | null;
-        image?: ImageSource | RemoteSource<ImageMetadata> | null;
+        image?: ImageSource | 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> {
@@ -124,7 +122,7 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
         }) => {
             title: string;
             subtitle?: string | null;
-            image?: ImageSource | RemoteSource<ImageMetadata> | null;
+            image?: ImageSource | null;
         };
     }): RecordSchema<T, K, Src>;
 }

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/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;