@valbuild/core 0.139.1 → 0.141.0

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

@@ -0,0 +1,249 @@
+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 { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
+import { FieldRender } from "../render.js";
+/**
+ * Turn an upload into an HLS stream, in the browser, before it is uploaded.
+ *
+ * The Studio transcodes the picked file with WebCodecs into one rendition per
+ * entry of `renditions` (never upscaled: a 720p upload gets no 1080p
+ * rendition), segments each into CMAF and writes the playlists. What is stored
+ * is a directory beside the other uploads; the field's `path` is its master
+ * playlist. See `architecture/media.md`.
+ *
+ * `type` is required for the same reason it is on `ImageEncodeOptions`: a
+ * second kind of stream would then be additive.
+ */
+export type VideoStreamOptions = {
+    type: "hls";
+    /**
+     * The heights of the renditions, in pixels. A rendition taller than the
+     * upload is skipped; if every one is, the upload's own height is used.
+     * @default [1080, 720, 480]
+     */
+    renditions?: number[];
+    /** Target length of each segment, in seconds. @default 6 */
+    segmentDuration?: number;
+};
+/** `false` (or absent) uploads the file as it was picked. */
+export type VideoStreamOption = false | VideoStreamOptions;
+export type VideoOptions = {
+    /** Where uploads land. @default "/public/val" */
+    dir?: string;
+    /**
+     * What may be UPLOADED, in `<input accept>` syntax. @default "video/*"
+     *
+     * Not checked against an HLS stream: the playlist is what the Studio made of
+     * an upload that was accepted, not something an editor picked.
+     */
+    accept?: string;
+    stream?: VideoStreamOption;
+};
+/**
+ * What a SET-BACKED field (`s.video(videosVal)`) may say for itself.
+ *
+ * Not `VideoOptions`: `dir` and `accept` belong to the set. `stream` is the
+ * exception, as `encode` is for an image: it is about what happens to an
+ * upload on its way in, so a field that wants the file as it was picked,
+ * where its set streams, has to be able to say `stream: false`.
+ */
+export type GalleryVideoOptions = {
+    stream?: VideoStreamOption;
+};
+/**
+ * The set a field picks from: its entries as they were when the module was
+ * evaluated (the published set — see `GalleryImageSource` for why that is
+ * enough), and whether it stores its videos on Val Remote.
+ */
+export type VideoGallery = {
+    modulePath: string;
+    /**
+     * `null` for a schema that was DESERIALIZED: the serialized form names the
+     * 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;
+    remote: boolean;
+};
+export type SerializedVideoSchema = {
+    type: "video";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
+    options?: VideoOptions;
+    opt: boolean;
+    remote?: boolean;
+    customValidate?: boolean;
+    /** The `s.videoset()` module this field picks from, if it is set-backed. */
+    referencedModule?: string;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+export type VideoMetadata = {
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+};
+export declare const DEFAULT_VIDEO_ACCEPT = "video/*";
+export declare const DEFAULT_VIDEO_RENDITIONS: number[];
+export declare const DEFAULT_VIDEO_SEGMENT_DURATION = 6;
+export declare class VideoSchema<Src extends GalleryVideoSource | null> extends Schema<Src> {
+    private readonly options?;
+    private readonly opt;
+    protected readonly isRemote: boolean;
+    private readonly customValidateFunctions;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    private readonly previewInput;
+    private readonly gallery;
+    constructor(options?: VideoOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null, gallery?: VideoGallery | null);
+    /**
+     * Describe this field.
+     *
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.video().describe("Plays muted behind the headline");
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.mp4",
+     *   mimeType: "video/mp4",
+     * });
+     */
+    describe(description: string | null): VideoSchema<Src>;
+    /**
+     * Store the video on Val's remote content host instead of in your
+     * repository.
+     *
+     * The bytes still go into the patch store when the video is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published video lives: `path` (and the poster's, and each caption track's)
+     * becomes a remote URL rather than a path under `/public`, so the repository
+     * does not grow with every upload. Upload remote videos in the Studio.
+     *
+     * @example
+     * const schema = s.video().remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/example.mp4",
+     *   mimeType: "video/mp4",
+     * });
+     */
+    remote(): VideoSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.video().validate((val) =>
+     *   (val.duration ?? 0) <= 30 ? false : "Keep it under 30 seconds",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.mp4",
+     *   mimeType: "video/mp4",
+     *   duration: 12,
+     * });
+     */
+    validate(validationFunction: CustomValidateFunction<Src>): VideoSchema<Src>;
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * A set-backed field: the file and what was read from it are the set's,
+     * so the field is checked for what is its own, and for pointing at an
+     * entry the set has.
+     */
+    private validateFromGallery;
+    /** A video of its own: it carries the file, and what was read from it. */
+    private validateOwn;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): VideoSchema<Src | null>;
+    readonly(isReadonly?: boolean): VideoSchema<Src>;
+    hidden(isHidden?: boolean): VideoSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.video().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.mp4", mimeType: "video/mp4" },
+     * ]);
+     */
+    render(input: FieldRender): VideoSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.video().preview(({ val }) => ({
+     *     title: val.alt ?? val.path,
+     *     image: val.poster,
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.mp4", mimeType: "video/mp4" },
+     * ]);
+     */
+    preview(select: ItemPreviewInput<Src>): VideoSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
+    protected executeSerialize(): SerializedSchema;
+}
+/**
+ * Every file a video value names: the video, its poster and each caption
+ * track. An HLS stream's segments are not here — they are named by its
+ * playlists, not by the value.
+ */
+export declare function filesOfVideoSource(src: GalleryVideoSource): string[];
+/**
+ * A video picked from a set (`s.videoset()`). 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>;
+/**
+ * Define a video: an `.mp4` / `.webm` file, or an HLS stream the Studio makes
+ * from an upload when `stream` is set.
+ */
+export declare function video(options?: VideoOptions): VideoSchema<VideoSource>;
+/**
+ * `s.video()` for a project whose media is all remote (`files.remote` in
+ * `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(options?: VideoOptions): VideoSchema<VideoSource>;

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

@@ -0,0 +1,141 @@
+import { Schema } from "./index.js";
+import type { 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 { SerializedVideoSchema, VideoStreamOption } from "./video.js";
+import type { MediaHotspot, VideoCaptionSource, VideoPosterSource } from "../source/media.js";
+/**
+ * Options for s.videoset()
+ */
+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> = [
+    StringSchema<string | null>
+] extends [Alt] ? {
+    /**
+     * Description schema. Can be:
+     * - s.string() for a required description
+     * - s.string().nullable() for an optional one (default)
+     * - s.record(s.string(), s.string()) for one per locale
+     */
+    alt?: Alt;
+} : {
+    /** Description schema — required, because it is not the default one. */
+    alt: Alt;
+};
+type VideosetOptionsBase<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`.
+     */
+    stream?: VideoStreamOption;
+};
+/**
+ * One video of a set, keyed by its file path (an HLS stream by its master
+ * playlist).
+ *
+ * Two kinds of thing are here. What is TRUE OF THE FILE — what it is, how
+ * big, how long — is read from the bytes and is the set's alone. The rest —
+ * the description, focal point, poster, start and end, and captions — is what
+ * a page chooses about a video, and an entry holds it as the DEFAULT: every
+ * field picked from the set (`s.video(videosVal)`) starts from it and may
+ * override it key by key, so a video described and trimmed once is described
+ * and trimmed everywhere it is used. `fillFromGallery` is the one merge.
+ *
+ * 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> = {
+    mimeType: string;
+    width: number;
+    height: number;
+    /** In seconds. */
+    duration: number;
+    alt: Alt;
+    hotspot?: MediaHotspot;
+    /** Seconds. The frame the poster was taken from. */
+    posterTime?: number;
+    poster?: VideoPosterSource;
+    /** Seconds. Where playback starts. */
+    startTime?: number;
+    /** Seconds. Where playback stops. */
+    endTime?: number;
+    /** 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> = {
+    mimeType: StringSchema<string>;
+    width: NumberSchema<number>;
+    height: NumberSchema<number>;
+    duration: NumberSchema<number>;
+    alt: Alt;
+};
+type VideosetItemSrc<Alt extends AltSchema> = {
+    mimeType: string;
+    width: number;
+    height: number;
+    duration: number;
+    alt: AltSourceOf<Alt>;
+};
+/**
+ * Define a collection of videos — the video twin of `s.imageset()`.
+ *
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.videoset({
+ *   dir: "/public/val/videos",
+ *   stream: { type: "hls" },
+ * });
+ * export default c.define("/content/videos.val.ts", schema, {
+ *   "/public/val/videos/intro_51df2.mp4": {
+ *     mimeType: "video/mp4",
+ *     width: 1280,
+ *     height: 720,
+ *     duration: 12.5,
+ *     alt: "The team, introducing itself",
+ *     startTime: 1.5,
+ *   },
+ * });
+ * ```
+ */
+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>>>>;
+/**
+ * The video schema a set's entry is hashed against, for a remote ref.
+ *
+ * The set's item schema is an object, but a remote ref's validation hash is
+ * computed over a MEDIA schema, so one is synthesized from the set — the one
+ * definition the CLI's upload (`videos:upload-remote`) and the Studio's (the
+ * set's gallery) both use, because two copies are two hashes for the same
+ * file. `stream` is left out: it says what is done to an upload on its way
+ * in, not whether the bytes that arrived are valid.
+ */
+export declare function videosetEntryVideoSchema(set: {
+    accept?: string;
+    dir?: string;
+}): SerializedVideoSchema;
+export {};

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

@@ -0,0 +1,20 @@
+import type { Schema } from "../schema/index.js";
+import type { SelectorSource } from "../selector/index.js";
+/**
+ * The PUBLISHED entries of every gallery a module's fields pick from — an
+ * `s.image(galleryVal)`, `s.file(filesVal)` or `s.video(videosVal)` — by the
+ * gallery's module path.
+ *
+ * A gallery-backed value names its file and nothing else that is the
+ * gallery's, so a reader has to look the entry up (`fillFromGallery`). In
+ * draft mode the reader has every module's draft source to look in; outside
+ * it, nothing — and the page got a set-backed video with no type, size,
+ * poster or description, and an image with no dimensions. But the field's
+ * schema was built from the gallery module (`s.video(videosVal)` reads it at
+ * definition), so the published entries are already here, on the schema
+ * instance. This is where they are read from.
+ *
+ * Stops at a view: the module it points at is read on its own, with its own
+ * galleries.
+ */
+export declare function galleriesOf(schema: Schema<SelectorSource> | undefined): Map<string, unknown>;

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

@@ -42,6 +42,119 @@ export type GalleryFileSource = {
 export type FileSource = GalleryFileSource & {
     readonly mimeType?: string;
 };
+/**
+ * The still shown before a video plays — `<video poster>`.
+ *
+ * Derived, like a video's `width` and `height`: the Studio grabs the frame at
+ * {@link VideoSource.posterTime} and uploads it as an image, so a page can show
+ * it without decoding the video. It is a media object of its own (a `path`,
+ * and a `patch_id` while unpublished) because it is a file of its own.
+ */
+export type VideoPosterSource = {
+    readonly path: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly mimeType?: string;
+    readonly patch_id?: string;
+};
+/**
+ * One text track of a video — `<track src srclang label kind default>`.
+ *
+ * `path` is a WebVTT file, uploaded like any other file.
+ */
+export type VideoCaptionSource = {
+    readonly path: string;
+    /** BCP 47 language tag of the track, e.g. `en` or `nb-NO`. */
+    readonly srclang: string;
+    /** What a viewer picks from the player's caption menu, e.g. "English". */
+    readonly label?: string;
+    /**
+     * `subtitles` translate the dialogue; `captions` also describe the sound,
+     * for viewers who cannot hear it. @default "subtitles"
+     */
+    readonly kind?: "subtitles" | "captions";
+    /** Shown without the viewer turning it on. At most one track may say so. */
+    readonly default?: boolean;
+    readonly patch_id?: string;
+};
+/**
+ * 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()`
+ * (`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
+ * used in two places can be trimmed and captioned differently in each.
+ *
+ * Times are in seconds from the start of the file.
+ */
+export type GalleryVideoSource = {
+    readonly path: string;
+    /** Describes the video for someone who cannot see it. */
+    readonly alt?: string;
+    /** What must stay in frame when a page crops the video (`object-position`). */
+    readonly hotspot?: MediaHotspot;
+    /** Seconds. The frame the poster was taken from. */
+    readonly posterTime?: number;
+    readonly poster?: VideoPosterSource;
+    /** Seconds. Where playback starts. */
+    readonly startTime?: number;
+    /** Seconds. Where playback stops. */
+    readonly endTime?: number;
+    readonly captions?: readonly VideoCaptionSource[];
+    /**
+     * 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;
+};
+/**
+ * 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
+ * set starts from and may override key by key. See {@link fillFromGallery}.
+ */
+export type VideoDefaults = Pick<GalleryVideoSource, "hotspot" | "posterTime" | "poster" | "startTime" | "endTime" | "captions">;
+/**
+ * A video: a progressive file (`video/mp4`, `video/webm`) or an HLS stream
+ * (`application/vnd.apple.mpegurl`, whose `path` is the master playlist).
+ *
+ * `mimeType` is REQUIRED on a video of its own: a page has to know which of
+ * the two it is holding before it can play it at all — an `.m3u8` handed to a
+ * `<video src>` plays only in Safari. (What tells a video's TYPE apart from an
+ * image's is its declared keys, see {@link IsVideoSource}, because a field
+ * picked from a set has no `mimeType` of its own.)
+ *
+ * `width`, `height`, `duration` and `mimeType` are read from the bytes;
+ * everything else is authored.
+ */
+export type VideoSource = GalleryVideoSource & {
+    readonly mimeType: string;
+    readonly width?: number;
+    readonly height?: number;
+    /** Seconds. */
+    readonly duration?: number;
+};
+/**
+ * Whether a source TYPE is a video's.
+ *
+ * Every media source is "a `path` plus optional fields", so assignability
+ * cannot tell an image from a video: an image is assignable to a set-backed
+ * video and the other way round. The keys a type DECLARES can — only a video
+ * declares `posterTime` — so the readers' conditional types ask this before
+ * they ask about images.
+ */
+export type IsVideoSource<T> = T extends {
+    readonly path: string;
+} ? "posterTime" extends keyof T ? true : false : false;
+/** The mime type of an HLS master playlist. */
+export declare const HLS_MIME_TYPE = "application/vnd.apple.mpegurl";
+/** Whether a video is an HLS stream rather than a single progressive file. */
+export declare function isHlsVideo(src: {
+    readonly path: string;
+    readonly mimeType?: string;
+}): boolean;
 /**
  * The structural supertype of every media source.
  *
@@ -50,7 +163,7 @@ export type FileSource = GalleryFileSource & {
  * `Source` excludes `undefined` — an object with optional properties does not
  * satisfy it.
  */
-export type MediaSource = ImageSource;
+export type MediaSource = ImageSource | VideoSource;
 /** A path is remote unless it is under `/public`. */
 export declare function isRemoteMediaPath(path: string): boolean;
 /**
@@ -76,23 +189,70 @@ export declare function resolveMedia<S extends {
     url: string;
 };
 /**
- * Fill in what a gallery-backed field does not carry itself.
+ * A video as a reader sees it: every file it names — the video itself, its
+ * poster and each caption track — carries the URL its bytes are served from.
  *
- * `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.
+ * Each gets its own {@link mediaUrl} because each is its own file with its own
+ * `patch_id`: replacing only the poster drafts the poster, and the video keeps
+ * its published URL.
+ */
+export type ResolvedVideo<S extends GalleryVideoSource = VideoSource> = Omit<S, "poster" | "captions"> & {
+    readonly url: string;
+    readonly poster?: VideoPosterSource & {
+        readonly url: string;
+    };
+    readonly captions?: readonly (VideoCaptionSource & {
+        readonly url: string;
+    })[];
+};
+/**
+ * The single implementation of {@link ResolvedVideo}. `url` is passed in as a
+ * function so the reader can tag the video's own URL (stega) without tagging
+ * 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>;
+/**
+ * What a gallery entry holds as a DEFAULT for the fields picked from it, in
+ * the groups a field overrides together.
  *
- * `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.
+ * Per key, not per value: a field that has set its own `startTime` still
+ * takes the gallery's `endTime`. The poster is the one pair — `poster` is the
+ * frame at `posterTime`, so a field with either has chosen its own still, and
+ * taking the other half from the gallery would describe a frame nobody chose.
+ */
+export declare const GALLERY_DEFAULT_GROUPS: readonly (readonly string[])[];
+/**
+ * The gallery entry a gallery-backed value names, or `null` when it is not
+ * 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.
  */
+export declare function galleryEntryOf(src: {
+    readonly path: string;
+}, schema: unknown, getModuleSource: (modulePath: string) => unknown): Record<string, unknown> | null;
+/**
+ * The value a gallery-backed field means: its own keys, and the gallery's
+ * where it has none.
+ *
+ * `s.image(galleryModule)` and `s.video(videosModule)` store only what one
+ * page chose — the rest lives in the gallery, keyed by path. Two things come
+ * from there:
+ *
+ * - **What is true of the file** — dimensions, mime type, length. The field
+ *   never has these, so they are always the gallery's.
+ * - **The defaults** — description, focal point, a video's poster, start, end
+ *   and captions ({@link GALLERY_DEFAULT_GROUPS}). An editor sets them once
+ *   on the gallery entry; a field that sets its own wins, KEY BY KEY.
+ *
+ * The single implementation of that merge: core, stega/RSC and the Studio all
+ * call it rather than each rolling their own, so a page and the Studio's
+ * preview of it cannot disagree about which poster a video has.
+ *
+ * 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.
+ */
 export declare function fillFromGallery<S extends {
     readonly path: string;
 }>(src: S, schema: unknown, getModuleSource: (modulePath: string) => unknown): S;

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

@@ -4,13 +4,15 @@ import { Val as ArrayVal } from "./array.js";
 import { Val as PrimitiveVal } from "./primitive.js";
 import { Json, JsonArray, JsonObject, JsonPrimitive } from "../Json.js";
 import { Path, Selector } from "../selector/index.js";
-import { MediaSource } from "../source/media.js";
+import { GalleryVideoSource, IsVideoSource, MediaSource, ResolvedVideo } from "../source/media.js";
 export type SerializedVal = {
     val: SerializedVal | Json;
     valPath: SourcePath | undefined;
 };
 export declare function isSerializedVal(val: unknown): val is SerializedVal;
-export type JsonOfSource<T extends Source> = Json extends T ? Json : T extends MediaSource ? T & {
+export type JsonOfSource<T extends Source> = Json extends T ? Json : T extends GalleryVideoSource ? IsVideoSource<T> extends true ? ResolvedVideo<T> : T & {
+    url: string;
+} : T extends MediaSource ? T & {
     url: string;
 } : T extends SourceObject ? {
     [key in keyof T]: JsonOfSource<T[key]>;