@valbuild/core 0.141.0 → 0.144.0

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

@@ -4,7 +4,7 @@ import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem } from "../preview.js";
-import { AltSource, ImagesetEntryMetadata } from "./imageset.js";
+import { AltSource, ImagedirEntryMetadata } from "./imagedir.js";
 /**
  * How an uploaded image is re-encoded in the browser, before it is uploaded.
  *
@@ -77,7 +77,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private readonly isHidden;
     private readonly description?;
     private readonly previewInput;
-    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesetEntryMetadata<AltSource>>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null);
+    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagedirEntryMetadata<AltSource>>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.
      *
@@ -204,7 +204,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
  * 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, ImagesetEntryMetadata<AltSource>>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
+export declare function image(galleryModule: ValModule<Record<string, ImagedirEntryMetadata<AltSource>>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
 /** An image of its own, carrying its own dimensions and mime type. */
 export declare function image(options?: ImageOptions): ImageSchema<ImageSource>;
 /**
@@ -212,5 +212,5 @@ export declare function image(options?: ImageOptions): ImageSchema<ImageSource>;
  * `val.config.ts`): the same schema, with `.remote()` already applied. See
  * `initSchema`.
  */
-export declare function remoteImage(galleryModule: ValModule<Record<string, ImagesetEntryMetadata<AltSource>>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
+export declare function remoteImage(galleryModule: ValModule<Record<string, ImagedirEntryMetadata<AltSource>>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
 export declare function remoteImage(options?: ImageOptions): ImageSchema<ImageSource>;

package/dist/declarations/src/schema/{imageset.d.ts → imagedir.d.ts}

@@ -1,6 +1,6 @@
 import { Schema } from "./index.js";
 import type { SelectorOfSchema } from "./index.js";
-import type { SerializedRecordSchema } from "./record.js";
+import type { MediaDir, SerializedRecordSchema } from "./record.js";
 import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
@@ -22,18 +22,32 @@ export type AltSourceOf<Alt extends AltSchema> = SelectorOfSchema<Alt>;
 /** Every `alt` value any `AltSchema` can produce. */
 export type AltSource = AltSourceOf<AltSchema>;
 /**
- * Options for s.imageset()
+ * Options for `s.imagedir(dir, options)`: everything but the directory, which
+ * is the first argument.
  */
-export type ImagesetOptions<Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>> = ImagesetOptionsBase<Accept> & ImagesetAltOption<Alt>;
+export type ImagedirOptions<Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>> = ImagedirOptionsBase<Accept> & ImagedirAltOption<Alt>;
+/**
+ * Options for the deprecated `s.imageset(options)`, which took the directory
+ * as `dir`.
+ *
+ * @deprecated Use `s.imagedir(dir, options)` and `ImagedirOptions`.
+ */
+export type ImagesetOptions<Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>> = ImagedirOptions<Accept, Alt> & {
+    /**
+     * The directory where images should be stored.
+     * Must start with "/public" (e.g., "/public/val/images")
+     */
+    dir: MediaDir;
+};
 /**
  * `alt` is optional only when it is the default schema.
  *
  * Naming a different `Alt` and then leaving `alt` out would make the fallback
- * in `imageset()` a lie — `Alt` would say `s.string()` while the value was a
+ * in `imagedir()` a lie — `Alt` would say `s.string()` while the value was a
  * nullable one. Requiring it in that case is what makes the fallback sound:
  * the branch that uses it is reachable only when `Alt` IS the default.
  */
-type ImagesetAltOption<Alt extends AltSchema> = [
+type ImagedirAltOption<Alt extends AltSchema> = [
     StringSchema<string | null>
 ] extends [Alt] ? {
     /**
@@ -47,27 +61,23 @@ type ImagesetAltOption<Alt extends AltSchema> = [
     /** Alt text schema — required, because it is not the default one. */
     alt: Alt;
 };
-type ImagesetOptionsBase<Accept extends `image/${string}`> = {
+/**
+ * The options argument of `s.imagedir()`: optional only when `alt` is, for
+ * the reason `ImagedirAltOption` gives — leaving the whole object out leaves
+ * `alt` out with it.
+ */
+type ImagedirOptionsArg<Accept extends `image/${string}`, Alt extends AltSchema> = [StringSchema<string | null>] extends [Alt] ? [options?: ImagedirOptions<Accept, Alt>] : [options: ImagedirOptions<Accept, Alt>];
+type ImagedirOptionsBase<Accept extends `image/${string}`> = {
     /**
      * The accepted mime type pattern. Must be an image type (e.g., "image/png", "image/webp", "image/*")
      * @default "image/*"
      */
     accept?: Accept;
-    /**
-     * The directory where images should be stored.
-     * Must start with "/public" (e.g., "/public/val/images")
-     *
-     * Required, and deliberately so: it decides where every uploaded file in this
-     * collection lands, and it used to default to "/public/val" — which meant a
-     * gallery that had simply not said where it wanted its files silently shared a
-     * directory with every other one.
-     */
-    dir: "/public" | `/public/${string}`;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
      * Off unless set. A field backed by this gallery (`s.image(galleryVal)`)
-     * inherits it, the same way it inherits `accept` and `directory`.
+     * inherits it, the same way it inherits `accept` and the directory.
      */
     encode?: ImageEncodeOption;
 };
@@ -76,10 +86,10 @@ type ImagesetOptionsBase<Accept extends `image/${string}`> = {
  *
  * `alt` follows the schema's `alt` option, so it defaults to `string | null`
  * and becomes `string` under `s.string()` or `Record<string, string>` under
- * `s.record(s.string())`. Write `ImagesetEntryMetadata<AltSource>` where a
+ * `s.record(s.string())`. Write `ImagedirEntryMetadata<AltSource>` where a
  * gallery of any alt shape is acceptable.
  */
-export type ImagesetEntryMetadata<Alt extends AltSource = string | null> = {
+export type ImagedirEntryMetadata<Alt extends AltSource = string | null> = {
     width: number;
     height: number;
     mimeType: string;
@@ -89,31 +99,37 @@ export type ImagesetEntryMetadata<Alt extends AltSource = string | null> = {
         y: number;
     };
 };
-export type SerializedImagesetSchema = SerializedRecordSchema;
-type ImagesetItemProps<Alt extends AltSchema> = {
+/** @deprecated Use `ImagedirEntryMetadata`. */
+export type ImagesetEntryMetadata<Alt extends AltSource = string | null> = ImagedirEntryMetadata<Alt>;
+export type SerializedImagedirSchema = SerializedRecordSchema;
+/** @deprecated Use `SerializedImagedirSchema`. */
+export type SerializedImagesetSchema = SerializedImagedirSchema;
+type ImagedirItemProps<Alt extends AltSchema> = {
     width: NumberSchema<number>;
     height: NumberSchema<number>;
     mimeType: StringSchema<string>;
     alt: Alt;
 };
-type ImagesetItemSrc<Alt extends AltSchema> = {
+type ImagedirItemSrc<Alt extends AltSchema> = {
     width: number;
     height: number;
     mimeType: string;
     alt: AltSourceOf<Alt>;
 };
+type ImagedirSchema<Alt extends AltSchema> = RecordSchema<ObjectSchema<ImagedirItemProps<Alt>, ImagedirItemSrc<Alt>>, Schema<string>, Record<string, ImagedirEntryMetadata<AltSourceOf<Alt>>>>;
 /**
- * Define a collection of images.
+ * Define a directory of images: a whole module that holds many images, keyed
+ * by their file path, that fields pick from with `s.image(galleryVal)`.
  *
- * `directory` is required — it decides where uploads land, so it is not something
- * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
- * text, remote disabled. Call `.remote()` on the result to allow remote images.
+ * The directory is the first argument and is required — it decides where
+ * uploads land, so it is not something to be inferred. The rest defaults: any
+ * image type (`"image/*"`), nullable alt text, remote disabled. Call
+ * `.remote()` on the result to allow remote images.
  *
  * @example
  * ```typescript
- * const schema = s.imageset({
+ * const schema = s.imagedir("/public/val/images", {
  *   accept: "image/webp",
- *   dir: "/public/val/images",
  *   alt: s.string().minLength(4),
  * });
  * export default c.define("/content/images.val.ts", schema, {
@@ -126,5 +142,23 @@ type ImagesetItemSrc<Alt extends AltSchema> = {
  * });
  * ```
  */
-export declare const imageset: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: ImagesetOptions<Accept, Alt>) => RecordSchema<ObjectSchema<ImagesetItemProps<Alt>, ImagesetItemSrc<Alt>>, Schema<string>, Record<string, ImagesetEntryMetadata<AltSourceOf<Alt>>>>;
+export declare const imagedir: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: ImagedirOptionsArg<Accept, Alt>) => ImagedirSchema<Alt>;
+/**
+ * `s.imagedir()` with `.remote()` applied: what `s.imagedir` is under
+ * `files: { remote: true }`.
+ */
+export declare const remoteImagedir: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: ImagedirOptionsArg<Accept, Alt>) => ImagedirSchema<Alt>;
+/**
+ * Define a collection of images.
+ *
+ * @deprecated Use `s.imagedir(dir, options)`: the directory moved out of the
+ * options and into the first argument, and nothing else changed.
+ *
+ * @example
+ * ```typescript
+ * // was: s.imageset({ dir: "/public/val/images", accept: "image/webp" })
+ * const schema = s.imagedir("/public/val/images", { accept: "image/webp" });
+ * ```
+ */
+export declare const imageset: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: ImagesetOptions<Accept, Alt>) => ImagedirSchema<Alt>;
 export {};

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

@@ -20,8 +20,19 @@ type MediaOptions = {
     /** Videos only: whether uploads become HLS streams. See `video.ts`. */
     stream?: VideoStreamOption;
 };
-/** What a media collection (`s.imageset`, `s.fileset`, `s.videoset`) holds. */
+/** What a media collection (`s.imagedir`, `s.filedir`, `s.videodir`) holds. */
 export type MediaCollectionType = "files" | "images" | "videos";
+/**
+ * Where a media collection keeps its files: the first argument of
+ * `s.imagedir()`, `s.filedir()`, `s.fontdir()` and `s.videodir()`.
+ *
+ * Required, and deliberately so: it decides where every uploaded file in the
+ * collection lands. It used to default to "/public/val", which meant a
+ * collection that had simply not said where it wanted its files silently
+ * shared a directory with every other one. It is the first argument rather
+ * than an option because it is the one thing every collection has to say.
+ */
+export type MediaDir = "/public" | `/public/${string}`;
 export type SerializedRecordSchema = {
     type: "record";
     item: SerializedSchema;
@@ -258,7 +269,7 @@ RO extends boolean = false> extends Schema<Src> {
      * Allow the files in this gallery to be stored on Val's remote content host
      * instead of in your repository.
      *
-     * For `s.imageset()` and `s.fileset()`, which are records of media. Remote is off
+     * For `s.imagedir()` and `s.filedir()`, which are records of media. Remote is off
      * until this is called.
      *
      * Each entry is then keyed by its URL on the content host rather than by a
@@ -267,7 +278,7 @@ RO extends boolean = false> extends Schema<Src> {
      * upload it and rewrite the key.
      *
      * @example
-     * const schema = s.imageset({ dir: "/public/val/images" }).remote();
+     * const schema = s.imagedir("/public/val/images").remote();
      * export default c.define("/content/images.val.ts", schema, {
      *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
      *     {
@@ -286,7 +297,7 @@ RO extends boolean = false> extends Schema<Src> {
      * 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.imageset()` / `s.fileset()`).
+     * Not supported on image/file galleries (`s.imagedir()` / `s.filedir()`).
      *
      * 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
@@ -313,7 +324,7 @@ RO extends boolean = false> extends Schema<Src> {
      * bucket — instead of in the module.
      *
      * Available on every record-derived schema, which is `s.record()`,
-     * `s.router()`, `s.imageset()` and `s.fileset()` alike: a router is a
+     * `s.router()`, `s.imagedir()` and `s.filedir()` alike: a router is a
      * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
      * four get external storage from this one method.
      *
@@ -396,7 +407,7 @@ RO extends boolean = false> extends Schema<Src> {
      * draws each entry's own editor in place, labelled by its key, instead of a
      * preview row that navigates to it. It reaches the direct entries only.
      *
-     * Not for `s.router(...)`, `s.imageset(...)` or `s.fileset(...)`: pages and
+     * Not for `s.router(...)`, `s.imagedir(...)` or `s.filedir(...)`: pages and
      * media have UIs of their own, so this throws on them.
      *
      * Static configuration, not a callback — see `render.ts`.

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

@@ -2,8 +2,8 @@ import { GalleryVideoSource, VideoSource } from "../source/media.js";
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { SourcePath } from "../val/index.js";
 import type { ValModule } from "../module.js";
-import type { AltSource } from "./imageset.js";
-import type { VideosetEntryMetadata } from "./videoset.js";
+import type { AltSource } from "./imagedir.js";
+import type { VideodirEntryMetadata } from "./videodir.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
@@ -67,7 +67,7 @@ export type VideoGallery = {
      * set, not its contents, so whether the set has the entry is a question
      * for the set's own module — which the Studio validates anyway.
      */
-    entries: Record<string, VideosetEntryMetadata<AltSource>> | null;
+    entries: Record<string, VideodirEntryMetadata<AltSource>> | null;
     remote: boolean;
 };
 export type SerializedVideoSchema = {
@@ -80,7 +80,7 @@ export type SerializedVideoSchema = {
     opt: boolean;
     remote?: boolean;
     customValidate?: boolean;
-    /** The `s.videoset()` module this field picks from, if it is set-backed. */
+    /** The `s.videodir()` module this field picks from, if it is set-backed. */
     referencedModule?: string;
     readonly?: boolean;
     hidden?: boolean;
@@ -230,11 +230,11 @@ export declare class VideoSchema<Src extends GalleryVideoSource | null> extends
  */
 export declare function filesOfVideoSource(src: GalleryVideoSource): string[];
 /**
- * A video picked from a set (`s.videoset()`). What is true of the file —
+ * A video picked from a set (`s.videodir()`). What is true of the file —
  * its type, size and length — lives in the set; the field carries what one
  * page chose about it.
  */
-export declare function video(videosetModule: ValModule<Record<string, VideosetEntryMetadata<AltSource>>>, galleryOptions?: GalleryVideoOptions): VideoSchema<GalleryVideoSource>;
+export declare function video(videosetModule: ValModule<Record<string, VideodirEntryMetadata<AltSource>>>, galleryOptions?: GalleryVideoOptions): VideoSchema<GalleryVideoSource>;
 /**
  * Define a video: an `.mp4` / `.webm` file, or an HLS stream the Studio makes
  * from an upload when `stream` is set.
@@ -245,5 +245,5 @@ export declare function video(options?: VideoOptions): VideoSchema<VideoSource>;
  * `val.config.ts`): the same schema, with `.remote()` already applied. See
  * `initSchema`.
  */
-export declare function remoteVideo(videosetModule: ValModule<Record<string, VideosetEntryMetadata<AltSource>>>, galleryOptions?: GalleryVideoOptions): VideoSchema<GalleryVideoSource>;
+export declare function remoteVideo(videosetModule: ValModule<Record<string, VideodirEntryMetadata<AltSource>>>, galleryOptions?: GalleryVideoOptions): VideoSchema<GalleryVideoSource>;
 export declare function remoteVideo(options?: VideoOptions): VideoSchema<VideoSource>;

package/dist/declarations/src/schema/{videoset.d.ts → videodir.d.ts}

@@ -1,18 +1,29 @@
 import { Schema } from "./index.js";
-import type { SerializedRecordSchema } from "./record.js";
+import type { MediaDir, SerializedRecordSchema } from "./record.js";
 import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 import { NumberSchema } from "./number.js";
-import type { AltSchema, AltSource, AltSourceOf } from "./imageset.js";
+import type { AltSchema, AltSource, AltSourceOf } from "./imagedir.js";
 import type { SerializedVideoSchema, VideoStreamOption } from "./video.js";
 import type { MediaHotspot, VideoCaptionSource, VideoPosterSource } from "../source/media.js";
 /**
- * Options for s.videoset()
+ * Options for `s.videodir(dir, options)`: everything but the directory, which
+ * is the first argument.
  */
-export type VideosetOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideosetOptionsBase<Accept> & VideosetAltOption<Alt>;
-/** See `ImagesetAltOption`: `alt` is optional only when it is the default. */
-type VideosetAltOption<Alt extends AltSchema> = [
+export type VideodirOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideodirOptionsBase<Accept> & VideodirAltOption<Alt>;
+/**
+ * Options for the deprecated `s.videoset(options)`, which took the directory
+ * as `dir`.
+ *
+ * @deprecated Use `s.videodir(dir, options)` and `VideodirOptions`.
+ */
+export type VideosetOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideodirOptions<Accept, Alt> & {
+    /** The directory where videos are stored. Must start with "/public". */
+    dir: MediaDir;
+};
+/** See `ImagedirAltOption`: `alt` is optional only when it is the default. */
+type VideodirAltOption<Alt extends AltSchema> = [
     StringSchema<string | null>
 ] extends [Alt] ? {
     /**
@@ -26,25 +37,20 @@ type VideosetAltOption<Alt extends AltSchema> = [
     /** Description schema — required, because it is not the default one. */
     alt: Alt;
 };
-type VideosetOptionsBase<Accept extends `video/${string}`> = {
+/** See `ImagedirOptionsArg`: the options are optional only when `alt` is. */
+type VideodirOptionsArg<Accept extends `video/${string}`, Alt extends AltSchema> = [StringSchema<string | null>] extends [Alt] ? [options?: VideodirOptions<Accept, Alt>] : [options: VideodirOptions<Accept, Alt>];
+type VideodirOptionsBase<Accept extends `video/${string}`> = {
     /**
      * What may be UPLOADED, in `<input accept>` syntax. Must be a video type.
      * Not checked against an HLS stream: see `VideoOptions.accept`.
      * @default "video/*"
      */
     accept?: Accept;
-    /**
-     * The directory where videos are stored. Must start with "/public".
-     *
-     * Required for the same reason it is on `s.imageset()`: it decides where
-     * every upload in the set lands, and a default is a directory shared with
-     * every other set that did not say.
-     */
-    dir: "/public" | `/public/${string}`;
     /**
      * Turn every upload into an HLS stream, in the browser. See
-     * `VideoStreamOptions`. A field backed by this set (`s.video(videosVal)`)
-     * inherits it, as it inherits `accept` and `dir`.
+     * `VideoStreamOptions`. A field backed by this directory
+     * (`s.video(videosVal)`) inherits it, as it inherits `accept` and the
+     * directory.
      */
     stream?: VideoStreamOption;
 };
@@ -63,7 +69,7 @@ type VideosetOptionsBase<Accept extends `video/${string}`> = {
  * The poster is also the set's thumbnail of the entry: there is no separate
  * still for the gallery, because two stills of one video would disagree.
  */
-export type VideosetEntryMetadata<Alt extends AltSource = string | null> = {
+export type VideodirEntryMetadata<Alt extends AltSource = string | null> = {
     mimeType: string;
     width: number;
     height: number;
@@ -81,34 +87,38 @@ export type VideosetEntryMetadata<Alt extends AltSource = string | null> = {
     /** Overridden as a whole: a field with its own tracks has none of these. */
     captions?: readonly VideoCaptionSource[];
 };
-export type SerializedVideosetSchema = SerializedRecordSchema;
-type VideosetItemProps<Alt extends AltSchema> = {
+/** @deprecated Use `VideodirEntryMetadata`. */
+export type VideosetEntryMetadata<Alt extends AltSource = string | null> = VideodirEntryMetadata<Alt>;
+export type SerializedVideodirSchema = SerializedRecordSchema;
+/** @deprecated Use `SerializedVideodirSchema`. */
+export type SerializedVideosetSchema = SerializedVideodirSchema;
+type VideodirItemProps<Alt extends AltSchema> = {
     mimeType: StringSchema<string>;
     width: NumberSchema<number>;
     height: NumberSchema<number>;
     duration: NumberSchema<number>;
     alt: Alt;
 };
-type VideosetItemSrc<Alt extends AltSchema> = {
+type VideodirItemSrc<Alt extends AltSchema> = {
     mimeType: string;
     width: number;
     height: number;
     duration: number;
     alt: AltSourceOf<Alt>;
 };
+type VideodirSchema<Alt extends AltSchema> = RecordSchema<ObjectSchema<VideodirItemProps<Alt>, VideodirItemSrc<Alt>>, Schema<string>, Record<string, VideodirEntryMetadata<AltSourceOf<Alt>>>>;
 /**
- * Define a collection of videos — the video twin of `s.imageset()`.
+ * Define a directory of videos — the video twin of `s.imagedir()`.
  *
  * A field picks from it with `s.video(videosVal)`. An entry may hold the
  * description, poster, start and end, focal point and captions as defaults,
  * and a field overrides any of them by setting its own. Uploading in such a
- * field adds to the set. Call `.remote()` on the result
- * to store the set on Val Remote.
+ * field adds to the directory. Call `.remote()` on the result to store the
+ * videos on Val Remote.
  *
  * @example
  * ```typescript
- * const schema = s.videoset({
- *   dir: "/public/val/videos",
+ * const schema = s.videodir("/public/val/videos", {
  *   stream: { type: "hls" },
  * });
  * export default c.define("/content/videos.val.ts", schema, {
@@ -123,7 +133,25 @@ type VideosetItemSrc<Alt extends AltSchema> = {
  * });
  * ```
  */
-export declare const videoset: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: VideosetOptions<Accept, Alt>) => RecordSchema<ObjectSchema<VideosetItemProps<Alt>, VideosetItemSrc<Alt>>, Schema<string>, Record<string, VideosetEntryMetadata<AltSourceOf<Alt>>>>;
+export declare const videodir: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: VideodirOptionsArg<Accept, Alt>) => VideodirSchema<Alt>;
+/**
+ * `s.videodir()` with `.remote()` applied: what `s.videodir` is under
+ * `files: { remote: true }`.
+ */
+export declare const remoteVideodir: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: VideodirOptionsArg<Accept, Alt>) => VideodirSchema<Alt>;
+/**
+ * Define a collection of videos.
+ *
+ * @deprecated Use `s.videodir(dir, options)`: the directory moved out of the
+ * options and into the first argument, and nothing else changed.
+ *
+ * @example
+ * ```typescript
+ * // was: s.videoset({ dir: "/public/val/videos", stream: { type: "hls" } })
+ * const schema = s.videodir("/public/val/videos", { stream: { type: "hls" } });
+ * ```
+ */
+export declare const videoset: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: VideosetOptions<Accept, Alt>) => VideodirSchema<Alt>;
 /**
  * The video schema a set's entry is hashed against, for a remote ref.
  *

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

@@ -81,7 +81,7 @@ export type VideoCaptionSource = {
  * What a video FIELD authors, on top of the file it names: the description,
  * the crop, the poster, the trim and the caption tracks.
  *
- * This is the whole value of a field picked from an `s.videoset()`
+ * This is the whole value of a field picked from an `s.videodir()`
  * (`s.video(videosetVal)`) — the mime type, size and length live in the set,
  * keyed by `path`, and repeating them here is how two copies of one fact get
  * to disagree. The poster, captions and times stay with the FIELD: one video
@@ -112,7 +112,7 @@ export type GalleryVideoSource = {
 /**
  * What one page chooses about a video — as opposed to what is true of the
  * file. A field (`s.video()`) carries these for itself; the entry of a set
- * (`s.videoset()`) carries them as DEFAULTS, which every field picked from the
+ * (`s.videodir()`) carries them as DEFAULTS, which every field picked from the
  * set starts from and may override key by key. See {@link fillFromGallery}.
  */
 export type VideoDefaults = Pick<GalleryVideoSource, "hotspot" | "posterTime" | "poster" | "startTime" | "endTime" | "captions">;
@@ -211,6 +211,27 @@ export type ResolvedVideo<S extends GalleryVideoSource = VideoSource> = Omit<S,
  * the poster's and the captions', which are not where an edit lands.
  */
 export declare function resolveVideo<S extends GalleryVideoSource>(src: S, videoUrl?: (src: S) => string): ResolvedVideo<S>;
+/**
+ * The key of a gallery (an `s.imagedir()`, `s.filedir()` or `s.videodir()`)
+ * that a field's `path` names, or `null` when it names none.
+ *
+ * Usually the path IS the key. It is not for an image uploaded THROUGH an
+ * `s.image(remoteGallery)` field in the Studio, which stores the remote ref in
+ * the field and keys the entry by the local path inside it — so a path that is
+ * not a key falls back to that embedded path. Exact first, because a gallery
+ * can hold both shapes for one file, and the field then names the entry that
+ * IS its path.
+ *
+ * One implementation of the question, asked by everything that has to agree on
+ * the answer: reading a field (`galleryEntryOf`), validating it (`ImageSchema`
+ * and `FileSchema` ask whether the gallery has it), the Studio's reference
+ * scans and renames, and `val validate --fix` when it renames a key and has to
+ * find the fields that hold it.
+ *
+ * The embedded path is tried with its leading slash (how a key is written) and
+ * without (how `splitRemoteRef` returns it).
+ */
+export declare function galleryKeyOf(path: string, isKey: (key: string) => boolean): string | null;
 /**
  * What a gallery entry holds as a DEFAULT for the fields picked from it, in
  * the groups a field overrides together.
@@ -226,7 +247,9 @@ export declare const GALLERY_DEFAULT_GROUPS: readonly (readonly string[])[];
  * gallery-backed or the gallery has no such entry.
  *
  * 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.
+ * remote URL while the file itself stays on disk under its local path, and an
+ * upload through the field does it the other way round (see
+ * {@link galleryKeyOf}).
  */
 export declare function galleryEntryOf(src: {
     readonly path: string;