@valbuild/server 0.140.2 → 0.141.1

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @valbuild/server
 
+## 0.141.1
+
+### Patch Changes
+
+- [#808](https://github.com/valbuild/val/pull/808) [`14b18d7`](https://github.com/valbuild/val/commit/14b18d7cb145cec1bc1cd832b9ca857ff4b45adc) Thanks [@freekh](https://github.com/freekh)! - A project with `files: { remote: true }` can save text edits without remote-file credentials: in local development without `val login` or a project id, and on a server without `VAL_API_KEY`.
+
+  Before, a save asked for remote credentials whenever any schema in the project was remote. With `files: { remote: true }` that is every media schema, so every save was refused, even a typo fix. Now it asks only when the change being saved contains a remote file.
+
+  When uploads are unavailable, the Studio now shows a card above the editor. It says what is wrong and gives the fix: a link to admin.val.build or the `val login` command to copy. When the cause is missing setup (no project id, not logged in, no API key) it also says that text edits still save and publish. Dismissing it leaves an "Uploads off" item in the status bar, or in the account sheet on a phone, that brings it back. This replaces the red bar that covered the top of the Studio, the Publish button included, and the login dialog that opened on every load.
+
+- Updated dependencies [[`6faacda`](https://github.com/valbuild/val/commit/6faacda398fc92bec187b7afe07a53228a6f2a3b), [`14b18d7`](https://github.com/valbuild/val/commit/14b18d7cb145cec1bc1cd832b9ca857ff4b45adc)]:
+  - @valbuild/ui@0.141.1
+
+## 0.141.0
+
+### Minor Changes
+
+- [#802](https://github.com/valbuild/val/pull/802) [`199e214`](https://github.com/valbuild/val/commit/199e21471d98806fb34c579cb876560078c928b9) Thanks [@freekh](https://github.com/freekh)! - New: `files: { remote: true }` in `val.config.ts` stores every image, file and video on Val's remote content host.
+
+  ```ts
+  const { s, c, val, config } = initVal({
+    project: "myorg/myproject",
+    files: { remote: true },
+  });
+  ```
+
+  With it, `s.image()`, `s.file()`, `s.video()`, `s.imageset()`, `s.fileset()`, `s.videoset()` and `s.richtext({ img: true })` behave as though `.remote()` had been written on them. Images already in the project are reported as `image:upload-remote` until they are uploaded; `npx val validate --fix` does that.
+
+  **Required in the Val app.** A project running there (`VAL_ENV=app`) refuses to start without it, with an error that says what to add, and `val publish` refuses before it builds.
+
+  **Breaking:** `files.directory` has been removed from `val.config.ts`. Local files that have no `dir` of their own are stored in `/public/val`, which was the default.
+
+- [#779](https://github.com/valbuild/val/pull/779) [`ba3f330`](https://github.com/valbuild/val/commit/ba3f3300a3dd8649e154097cdfca3b64db209d89) Thanks [@freekh](https://github.com/freekh)! - New: `s.video()`, for mp4/WebM files and HLS streams.
+
+  ```ts
+  const schema = s.object({
+    intro: s.video({ stream: { type: "hls" } }),
+  });
+  ```
+
+  - **Upload and play in the Studio.** A video field shows a player, the file's size and length, and progress while it uploads.
+  - **HLS streaming without a video service.** With `stream: { type: "hls" }`, the Studio converts an upload to an HLS stream in the editor's browser before it uploads it. It makes one H.264 rendition per height (1080p, 720p and 480p by default, and never larger than the upload) and stores them as a folder of files next to your other uploads. Nothing is installed in your app for this: the converter ships inside the Studio and is only downloaded when someone uploads to a streaming field. A browser that can't convert (no WebCodecs, or a non-https address) uploads the original file and says so.
+  - **Poster:** pause on a frame and choose "Use current frame". The frame is saved as an image, and `posterTime` records where it was taken.
+  - **Start and end:** play part of a video without cutting the file.
+  - **Focal point:** marks what must stay in frame when the page crops the video.
+  - **Description:** text for people who can't see the video.
+  - **Captions:** one WebVTT file per language. `.srt` files are converted on upload.
+  - **`<ValVideo>`** in `@valbuild/next` and `@valbuild/tanstack` renders all of the above and is click-to-edit. For HLS in browsers that can't play it natively, pass `hls={() => import("hls.js")}`. It is only loaded when it's needed.
+  - **Rename** a video in the Studio. An HLS stream is renamed as a whole: every playlist and segment moves to the new folder.
+  - `npx val validate --fix` fills in `mimeType`, `width`, `height` and `duration` for a hand-written `.mp4`, `.mov`, `.webm`, `.mkv` or HLS video, on disk or on Val Remote. A remote video is not downloaded: only its headers are read, usually in one to three small requests.
+  - `.remote()` works for videos. `npx val validate --fix` moves a video to Val Remote, or back into the project, together with its poster, captions and every file of an HLS stream.
+
+  A video value always has a `mimeType`: it is how a page knows whether it has an `.mp4` or an `.m3u8`.
+
+  New: `s.videoset()`, a collection of videos, like `s.imageset()` for images.
+
+  ```ts
+  const videosVal = c.define(
+    "/content/videos.val.ts",
+    s.videoset({ dir: "/public/val/videos", stream: { type: "hls" } }),
+    {},
+  );
+  const schema = s.object({ intro: s.video(videosVal) });
+  ```
+
+  - **Upload once, set it up once, use anywhere.** A set's entry holds what is true of the file (its type, size and length) and, as defaults, a description, poster, start and end, focal point and captions. A field that picks from the set (`s.video(videosVal)`) gets all of those, and can override any of them on its own. For example, the same clip can open one page at 0:02 and every other page where the set says.
+  - **Media in the Studio.** A set is listed under Media and opens as a gallery of videos, with each video's poster as its thumbnail. Hovering a video previews it, and the selected video plays in a real player (HLS streams too) beside the poster, times, focal point and captions you edit for it. You can upload into the set (with `stream`, uploads become HLS streams, and each upload gets a poster), rename a video, and delete a video that nothing uses. Renaming a video updates every field that uses it. An HLS stream is one entry, and renaming or deleting it moves or removes all of its files.
+  - **Picking.** A set-backed field picks from the set, or uploads into it. Each value the set provides is marked "From gallery · Override", and once overridden, "Overridden · Use gallery's".
+  - `useVal` and `fetchVal` fill in what the set holds (`mimeType`, `width`, `height`, `duration`, and every default the field does not override), so `<ValVideo>` works the same either way.
+  - `.remote()` works for sets. `npx val validate --fix` fills in missing metadata for an entry, adds untracked videos found in the set's directory, and moves a set's videos to Val Remote.
+
+  Image and file galleries use the same new gallery layout: a grid or list of entries, with the selected one open in a panel beside it.
+
+  - An `s.imageset()` entry can hold a default focal point, as well as its description. An `s.image(galleryVal)` field shows both, and can override either.
+  - Fixed: outside draft mode, `useVal` and `fetchVal` now fill a gallery-backed image or file from its gallery (dimensions, mime type, description). Before, a published page got only the `path`.
+
+### Patch Changes
+
+- Updated dependencies [[`199e214`](https://github.com/valbuild/val/commit/199e21471d98806fb34c579cb876560078c928b9), [`9cbe428`](https://github.com/valbuild/val/commit/9cbe42895d006d55c3d993dc27f0779808b85306), [`fb5f097`](https://github.com/valbuild/val/commit/fb5f09721ac07f4d90b8502fdbee3fb3884d9688), [`6473a2e`](https://github.com/valbuild/val/commit/6473a2efe874f1749b27ed6f8ac4e0d19805edb1), [`ba3f330`](https://github.com/valbuild/val/commit/ba3f3300a3dd8649e154097cdfca3b64db209d89)]:
+  - @valbuild/core@0.141.0
+  - @valbuild/shared@0.141.0
+  - @valbuild/ui@0.141.0
+
 ## 0.140.2
 
 ### Patch Changes

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

@@ -594,6 +594,19 @@ export declare abstract class ValOps {
     abstract getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Buffer | null>;
     protected abstract getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, remote: boolean): Promise<OpsMetadata<T>>;
     abstract getBinaryFile(filePathOrRef: string): Promise<Buffer | null>;
+    /**
+     * A file's bytes as something a `Range` request can be answered from
+     * without reading the rest: a video is seeked in by many small ranges, and
+     * each used to load the whole file.
+     *
+     * This default holds the whole file, which is all a mode that only gets
+     * whole files can do (`ValOpsHttp`: the content service answers with the
+     * file in a JSON body). `ValOpsFS` reads only the asked-for range off disk.
+     */
+    openBinaryFile(filePath: string, fromPatch: {
+        patchId: PatchId;
+        remote: boolean;
+    } | null): Promise<BinaryFileReader | null>;
     protected abstract getBinaryFileMetadata<T extends "file" | "image">(filePath: string, type: T): Promise<OpsMetadata<T>>;
     abstract deletePatches(patchIds: PatchId[]): Promise<{
         deleted: PatchId[];
@@ -977,3 +990,10 @@ export declare function getFieldsForType<T extends BinaryFileType>(type: T): (ke
 export declare function createMetadataFromBuffer<T extends BinaryFileType>(type: BinaryFileType, mimeType: string, buffer: Buffer): OpsMetadata<T>;
 export declare function guessMimeTypeFromPath(filePath: string): string | null;
 export declare function bufferFromDataUrl(dataUrl: string): Buffer | undefined;
+/** A file of known size whose bytes are read a range at a time. */
+export type BinaryFileReader = {
+    readonly size: number;
+    /** Bytes `start` to `end`, both inclusive, as an HTTP range is. */
+    read(start: number, end: number): Promise<Buffer>;
+};
+export declare function bufferReader(buffer: Buffer): BinaryFileReader;

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

@@ -1,5 +1,5 @@
 import { PatchId, ModuleFilePath, ValModules } from "@valbuild/core";
-import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
+import { AuthorId, BaseSha, BinaryFileType, BinaryFileReader, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
 import { Patch, ParentRef, ValCommit } from "@valbuild/shared/internal";
 import type { HistoryError } from "./history/HistoryError.js";
 import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
@@ -162,6 +162,10 @@ export declare class ValOpsFS extends ValOps {
             filePath?: string;
         }>;
     }>;
+    openBinaryFile(filePath: string, fromPatch: {
+        patchId: PatchId;
+        remote: boolean;
+    } | null): Promise<BinaryFileReader | null>;
     getBinaryFile(filePath: string): Promise<Buffer | null>;
     protected getBinaryFileMetadata<T extends BinaryFileType>(filePath: string, type: T): Promise<OpsMetadata<T>>;
     private getPatchesDir;

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

@@ -1,4 +1,4 @@
-import { FileMetadata, ImageMetadata, SerializedSchema, Source, SourcePath, ValidationError } from "@valbuild/core";
+import { FileMetadata, ImageMetadata, VideoMetadata, SerializedSchema, Source, SourcePath, ValidationError } from "@valbuild/core";
 import { JSONValue, Patch } from "@valbuild/core/patch";
 export type FixPatchRemainingError = ValidationError & {
     sourcePath?: SourcePath;
@@ -21,10 +21,12 @@ export declare function createFixPatch(config: {
     [sourcePath: SourcePath]: {
         ref: string;
         metadata?: Record<string, unknown>;
+        refs?: Record<string, string>;
     };
 }, moduleSource?: Source, moduleSchema?: SerializedSchema): Promise<{
     patch: Patch;
     remainingErrors: FixPatchRemainingError[];
 } | undefined>;
+export declare function getVideoMetadata(projectRoot: string, fileRef: string): Promise<VideoMetadata>;
 export declare function getImageMetadata(projectRoot: string, validationError: ValidationError): Promise<ImageMetadata>;
 export declare function getFileMetadata(projectRoot: string, validationError: ValidationError): Promise<FileMetadata>;

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

@@ -1,4 +1,50 @@
-import { FileMetadata, ImageMetadata } from "@valbuild/core";
+import { FileMetadata, ImageMetadata, VideoMetadata } from "@valbuild/core";
 import { Buffer } from "buffer";
+import { type ByteSource } from "./isoBmff.js";
 export declare function extractImageMetadata(filename: string, input: Buffer): Promise<ImageMetadata>;
 export declare function extractFileMetadata(filename: string, _input: Buffer): Promise<FileMetadata>;
+/**
+ * What `val validate --fix` writes into a video: `mimeType`, `width`, `height`
+ * and `duration`, read from the file. A field that cannot be read is left out
+ * rather than guessed, and the caller reports it — see
+ * {@link unreadableVideoMetadataMessage}.
+ *
+ * `mimeType` always comes from the file EXTENSION: validation compares the two,
+ * so any other answer is one validation rejects. The rest depends on the kind
+ * of file:
+ *
+ * - **ISO BMFF** (`.mp4`, `.m4v`, `.mov`): read from the `moov` box by a small
+ *   parser of our own (`isoBmff.ts`). No media library: this package is loaded
+ *   by every app that runs Val.
+ * - **WebM / Matroska** (`.webm`, `.mkv`): read from the Segment's Info and Tracks by another
+ *   (`ebml.ts`). A WebM recorded in a browser does not declare its length, and
+ *   then `duration` is left out — the frames are not counted to find it.
+ * - **An HLS master playlist** (`.m3u8`): the dimensions are the largest
+ *   rendition's `RESOLUTION`, and the duration is the sum of the `#EXTINF`s of
+ *   the first media playlist it names, read from disk beside it — which is why
+ *   `filename` must be the playlist's path on disk.
+ * - **Anything else**: the mime type and nothing more. The Studio reads those
+ *   in the browser when they are uploaded.
+ */
+export declare function extractVideoMetadata(filename: string, input: Buffer, readFile?: (absolutePath: string) => Buffer | undefined): Promise<VideoMetadata>;
+/**
+ * {@link extractVideoMetadata} for a file on disk, reading only the headers
+ * it needs: a video's frames (an mp4's `mdat`, a WebM's Clusters) are most of
+ * the file, and are skipped, not loaded.
+ */
+export declare function extractVideoMetadataFromFile(absolutePath: string): Promise<VideoMetadata>;
+/**
+ * What to tell someone whose video's `fields` could not be read. Names the
+ * way out, because "could not read" alone leaves them nowhere to go.
+ */
+export declare function unreadableVideoMetadataMessage(fileRef: string, fields: readonly string[]): string;
+/** Whether Val reads this video's size and length itself, by its extension. */
+export declare function canReadVideoMetadata(fileRef: string): boolean;
+export declare function extractFromByteSource(filename: string, source: ByteSource): VideoMetadata;
+/**
+ * An HLS stream's metadata from its master playlist's text, and — for the
+ * duration — the first media playlist it names, which `readMediaPlaylist`
+ * fetches by the URI the master gives (relative to it, or a remote ref). The
+ * one implementation for a stream on disk and one on Val Remote.
+ */
+export declare function readHlsMetadata(text: string, readMediaPlaylist: (uri: string) => Promise<string | undefined>): Promise<VideoMetadata>;

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

@@ -27,9 +27,12 @@
  * walks every module, decides what to report, and renders it to a terminal.
  */
 import { ModuleFilePath, SourcePath, ValidationFix } from "@valbuild/core";
+import { checkGalleryFiles } from "./galleryFiles.js";
 import type { Service } from "./Service.js";
 import type { IValFSHost } from "./ValFSHost.js";
+import type { Patch } from "@valbuild/core/patch";
 export type { IValFSHost };
+export { checkGalleryFiles };
 export type IValRemote = {
     remoteHost: string;
     getSettings(projectName: string, options: {
@@ -73,27 +76,49 @@ export type FixHandlerContext = {
     moduleFilePath: ModuleFilePath;
     file: string;
     fs: IValFSHost;
-    remoteFiles: Record<SourcePath, {
-        ref: string;
-        metadata?: Record<string, unknown>;
-    }>;
+    remoteFiles: Record<SourcePath, RemoteFileMove>;
     publicProjectId?: string;
     remoteFileBuckets?: string[];
     remoteFilesCounter: number;
     remote: IValRemote;
     project: string | undefined;
 };
+/**
+ * Where a fix moved a media value's file. `refs` is for a value that names
+ * SEVERAL files — a video's poster, captions and stream — keyed by the path
+ * the value held, so the patch can rewrite each one where it is.
+ */
+export type RemoteFileMove = {
+    ref: string;
+    metadata?: Record<string, unknown>;
+    refs?: Record<string, string>;
+};
 export type FixHandlerResult = {
     success: boolean;
     errorMessage?: string;
     shouldApplyPatch?: boolean;
     appliedFix?: boolean;
     fixableErrorMessage?: string;
+    /**
+     * Patches to OTHER modules than the one the fix is about, for the caller to
+     * apply alongside the fix's own patch (and only when it applies that one).
+     *
+     * A fix normally rewrites one value. Renaming a key that other modules name
+     * cannot be one: `videos:upload-remote` renames a set entry's key to its
+     * remote ref, and every `s.video(set)` field holding the old key would name
+     * a video the set no longer has.
+     */
+    otherModulePatches?: ModulePatch[];
     publicProjectId?: string;
     remoteFileBuckets?: string[];
     remoteFilesCounter?: number;
     events?: ValidationEvent[];
 };
+/** A patch, and the module it is for. */
+export type ModulePatch = {
+    moduleFilePath: ModuleFilePath;
+    patch: Patch;
+};
 export type FixHandler = (ctx: FixHandlerContext) => Promise<FixHandlerResult>;
 export type ValidationEvent = {
     type: "file-valid";
@@ -157,40 +182,20 @@ export type ValidationEvent = {
     type: "summary-success";
 };
 export declare function handleFileMetadata(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `video:add-metadata`: the bytes must be on disk, or on Val Remote (read
+ * over HTTP, headers only — see `remoteVideoMetadata.ts`), and they must be a
+ * kind of file Val can read the size and length of here: mp4/mov boxes,
+ * WebM/Matroska headers and HLS playlists. Anything else is refused with what
+ * to do instead, unless all that is missing is the mime type, which the
+ * extension answers.
+ */
+export declare function handleVideoMetadata(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleRemoteFileUpload(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleRemoteGalleryFileUpload(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleRemoteFileDownload(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleRemoteFileCheck(): Promise<FixHandlerResult>;
 export declare function handleUniqueFolderCheck(ctx: FixHandlerContext): Promise<FixHandlerResult>;
-/**
- * What is out of step between a gallery's entries and its directory.
- *
- * Two questions, and they treat a remote entry differently — which is the whole
- * reason this is separate from the handler around it:
- *
- * - **Missing**: an entry with no bytes at its local path. Asked of LOCAL
- *   entries only. A remote entry's bytes live on the content host, and nothing
- *   puts a copy in the working tree: `saveOrUploadFiles` uploads the remote
- *   descriptors and copies only the local ones into the tree, so a remote entry
- *   added through the Studio (or over MCP) has no local file by design, and
- *   demanding one would mean committing remote bytes to git — which is what
- *   remote storage exists to avoid. Whether those bytes really are on the host
- *   is a different check, `image:check-remote`, which already runs for exactly
- *   these entries.
- * - **Untracked**: a file in the directory that no entry claims. Asked of every
- *   entry, remote included, and that is why they are normalised to their local
- *   path: `val validate --fix` promotes a local file to a remote ref and leaves
- *   the file where it was, so a remote entry can perfectly well have one.
- */
-export declare function checkGalleryFiles(input: {
-    entryKeys: string[];
-    dir: string;
-    projectRoot: string;
-    fs: Pick<IValFSHost, "fileExists" | "readDirectory">;
-}): {
-    missingTrackedFiles: string[];
-    untrackedFiles: string[];
-};
 export declare function handleCheckAllFiles(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleJsonValuesExtractEntry(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 /**

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

@@ -0,0 +1,35 @@
+/**
+ * A gallery entry's key, read as what it actually is.
+ *
+ * A gallery is a record keyed by its entries' file paths. A REMOTE gallery keys
+ * an uploaded entry by the remote URL instead — which encodes that same path —
+ * so every entry has a local path, and the interesting question is whether the
+ * bytes are expected to be at it.
+ *
+ * **They are not, for a remote entry added the ordinary way.** `saveOrUploadFiles`
+ * uploads the remote descriptors to the content host and copies only the local
+ * ones into the working tree, so an image added through the Studio (or over MCP)
+ * and published has no file in the repo, by design — putting one there is what
+ * remote storage exists to avoid. A remote entry CAN have one, because
+ * `val validate --fix` promotes a local file to a remote ref and leaves the file
+ * where it was; so "remote" means "do not require it", never "there is not one".
+ *
+ * One copy, in its own file, because this used to be two: a `remoteKeyToLocalPath`
+ * in `fixHandlers` and a `galleryKeyToLocalPath` in `createFixPatch`, each
+ * normalising the key correctly and each then treating the result as a file that
+ * must exist. That agreement is what made a published remote image report as
+ * missing from both sides at once.
+ */
+export type GalleryEntryKey = {
+    /**
+     * Where the bytes are, or would be, in the working tree.
+     *
+     * The key itself for a remote key that does not parse — there is no such
+     * place for one, and nothing reads this for a remote entry except the
+     * untracked-files comparison, where a URL matches no file.
+     */
+    localPath: string;
+    /** True when the key is a URL, so a local file is not required. */
+    remote: boolean;
+};
+export declare function galleryEntryOf(key: string): GalleryEntryKey;

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

@@ -0,0 +1,59 @@
+import { type GalleryEntryKey } from "./galleryEntryKey.js";
+import type { IValFSHost } from "./ValFSHost.js";
+/**
+ * What is out of step between a gallery's entries and its directory.
+ *
+ * Two questions, and they treat a remote entry differently — which is the whole
+ * reason this is separate from the handler around it:
+ *
+ * - **Missing**: an entry with no bytes at its local path. Asked of LOCAL
+ *   entries only. A remote entry's bytes live on the content host, and nothing
+ *   puts a copy in the working tree: `saveOrUploadFiles` uploads the remote
+ *   descriptors and copies only the local ones into the tree, so a remote entry
+ *   added through the Studio (or over MCP) has no local file by design, and
+ *   demanding one would mean committing remote bytes to git — which is what
+ *   remote storage exists to avoid. Whether those bytes really are on the host
+ *   is a different check, `image:check-remote`, which already runs for exactly
+ *   these entries.
+ * - **Untracked**: a file in the directory that no entry claims. Asked of every
+ *   entry, remote included, and that is why they are normalised to their local
+ *   path: `val validate --fix` promotes a local file to a remote ref and leaves
+ *   the file where it was, so a remote entry can perfectly well have one.
+ *
+ * An entry can claim more than its key. A video set's HLS stream is keyed by
+ * its master playlist, and the media playlists and segments it names are the
+ * same entry — so `filesOfEntry` says what else an entry holds, and those are
+ * not untracked either.
+ *
+ * Its own module rather than a part of `fixHandlers.ts`, so the video set's
+ * fixes can use it without importing the handler registry they are part of.
+ */
+export declare function checkGalleryFiles(input: {
+    entryKeys: string[];
+    dir: string;
+    projectRoot: string;
+    fs: Pick<IValFSHost, "fileExists" | "readDirectory">;
+    /**
+     * Every file an entry holds besides its key, as `/public/…` refs. Asked of
+     * every entry, for the same reason untracked is.
+     */
+    filesOfEntry?: (entry: GalleryEntryKey, key: string) => string[];
+}): {
+    missingTrackedFiles: string[];
+    untrackedFiles: string[];
+};
+/**
+ * The LOCAL entries whose key is there but some of what they hold is not: a
+ * stream missing a segment plays up to the gap and then stops. Separate from
+ * `checkGalleryFiles`' "missing" because a fix does not remove these — the
+ * entry still names a video someone uploaded and may have the rest of.
+ */
+export declare function incompleteGalleryEntries(input: {
+    entryKeys: string[];
+    projectRoot: string;
+    fs: Pick<IValFSHost, "fileExists">;
+    filesOfEntry: (entry: GalleryEntryKey, key: string) => string[];
+}): {
+    key: string;
+    missing: string[];
+}[];

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

@@ -4,6 +4,7 @@ export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder,
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
 export { resolveRemoteFileAuth } from "./valServerConfig.js";
+export { APP_MODE_REQUIRES_REMOTE_FILES } from "./valServerConfig.js";
 export type { RemoteFileAuth, ResolveRemoteFileAuthResult, } from "./valServerConfig.js";
 export { ValModuleLoader } from "./ValModuleLoader.js";
 export { getCompilerOptions } from "./getCompilerOptions.js";
@@ -17,13 +18,15 @@ export { analyzeValModule } from "./patch/ts/valModule.js";
 export type { ValModuleAnalysis } from "./patch/ts/valModule.js";
 export { createFixPatch } from "./createFixPatch.js";
 export { fixHandlers, currentFixHandlers, createDefaultValFSHost, handleFileMetadata, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleRemoteFileDownload, handleRemoteFileCheck, handleUniqueFolderCheck, handleCheckAllFiles, handleJsonValuesExtractEntry, handleExternalUpload, } from "./fixHandlers.js";
-export type { FixHandler, FixHandlerContext, FixHandlerResult, IValRemote, ValidationEvent, ValidationError, ValModule, } from "./fixHandlers.js";
+export { handleVideosetMetadata, handleVideosetUploadRemote, handleVideosetCheckRemote, handleVideosetCheckAllFiles, videosetEntryVideoSchema, filesOfVideosetEntry, } from "./videosetFixes.js";
+export type { FixHandler, ModulePatch, FixHandlerContext, FixHandlerResult, IValRemote, ValidationEvent, ValidationError, ValModule, } from "./fixHandlers.js";
 export * from "./jwt.js";
 export type { ValServer } from "./ValServer.js";
 export { getSettings } from "./getSettings.js";
 export { getPersonalAccessTokenPath, parsePersonalAccessTokenFile, } from "./personalAccessTokens.js";
 export { uploadRemoteFile } from "./uploadRemoteFile.js";
-export { extractImageMetadata, extractFileMetadata } from "./extractMetadata.js";
+export { extractImageMetadata, extractFileMetadata, extractVideoMetadata, extractVideoMetadataFromFile, } from "./extractMetadata.js";
+export { filesOfVideo } from "./videoFiles.js";
 export { validateMetadata } from "./validateMetadata.js";
 export { getValidationErrorFileRef } from "./getValidationErrorFileRef.js";
 export { checkRemoteRef, downloadFileFromRemote, getCachedRemoteFileDir, getCachedRemoteFilePath, } from "./checkRemoteRef.js";

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

@@ -0,0 +1,41 @@
+/**
+ * The size and length of an ISO base media file (`.mp4`, `.m4v`, `.mov`),
+ * read from its headers. Nothing is decoded.
+ *
+ * Hand-written rather than a media library, deliberately: `@valbuild/server`
+ * is loaded by every app that runs Val, and the four numbers wanted here are
+ * three small boxes away from the start of the `moov` box:
+ *
+ *   moov > mvhd                  timescale and duration (version 0 and 1)
+ *   moov > mvex > mehd           duration of a FRAGMENTED file, whose mvhd says 0
+ *   moov > trak > tkhd           width and height (16.16 fixed point) and the
+ *                                display matrix, for a rotated phone video
+ *   moov > trak > mdia > hdlr    `vide`: which trak is the picture
+ *
+ * Only the box headers are read on the way to `moov`, and then `moov` itself,
+ * so a multi-GB file costs a few small reads: `mdat` is seeked past, never
+ * loaded. That is what {@link ByteSource} is for.
+ */
+/** Random access to a file's bytes, so a large `mdat` can be skipped. */
+export type ByteSource = {
+    readonly size: number;
+    /** Up to `length` bytes from `offset`; fewer only at the end of the file. */
+    read(offset: number, length: number): Buffer;
+};
+export declare function bufferByteSource(buffer: Buffer): ByteSource;
+/**
+ * Run `read` against a file on disk, reading only what it asks for. The file
+ * is closed afterwards whatever happens.
+ */
+export declare function withFileByteSource<T>(absolutePath: string, read: (source: ByteSource) => T): T;
+export type IsoBmffMetadata = {
+    width?: number;
+    height?: number;
+    /** Seconds, unrounded. */
+    duration?: number;
+};
+/**
+ * Whatever of {@link IsoBmffMetadata} the file declares. A field that cannot be
+ * read is absent; nothing here throws on a file that is not ISO BMFF.
+ */
+export declare function readIsoBmffMetadata(source: ByteSource): IsoBmffMetadata;

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

@@ -24,6 +24,14 @@ import { ValOpsMemory } from "./ValOpsMemory.js";
  * exists to avoid.
  */
 export declare const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
+/**
+ * What the Val app says when a project does not store its media remotely.
+ *
+ * Exported so that `val publish` -- which publishes to the app, and so is
+ * the last place to catch this before a build goes out -- refuses with the
+ * same sentence the deployed server would.
+ */
+export declare const APP_MODE_REQUIRES_REMOTE_FILES: string;
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *

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

@@ -0,0 +1,22 @@
+/**
+ * Every file a video value names, as refs (`/public/…`, or a remote URL as
+ * written): the video, its poster, each caption track — and, for a LOCAL HLS
+ * stream, every file its playlists name, followed from the master down through
+ * each media playlist to the segment files, init sections and audio tracks.
+ *
+ * Followed rather than "everything in the master's directory": the Studio
+ * gives each stream a directory of its own, but nothing stops a hand-placed
+ * `/public/val/clip.m3u8`, and the directory of THAT one is every file in
+ * `/public/val`. A file in a stream's directory that no playlist names is not
+ * used by the stream either, so calling it unused is right.
+ *
+ * A remote stream's playlists are on the content host, so its master is all
+ * that is named here.
+ *
+ * The one place that answers this, so `list-unused-files` and anything else
+ * asking "is this file used" agree on what a video holds.
+ */
+export declare function filesOfVideo(video: unknown, options: {
+    projectRoot: string;
+    readFile?: (absolutePath: string) => Buffer | undefined;
+}): string[];