@valbuild/server 0.140.0 → 0.141.0

package/dist/valbuild-server.esm.js

@@ -8,7 +8,7 @@ import path__default from 'path';
 import fs from 'fs';
 import vm from 'node:vm';
 import { Module } from 'node:module';
-import { isSchemaSourceFixError, resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, PatchId as PatchId$1, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, parseJob, VAL_STUDIO_HEADER, Api } from '@valbuild/shared/internal';
+import { isSchemaSourceFixError, resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, PatchId as PatchId$1, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, parseJob, VAL_STUDIO_HEADER, Api, traverseSchemaSource } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
 import z$1, { z } from 'zod';
@@ -18,6 +18,7 @@ import net from 'node:net';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
 import os from 'os';
+import { Buffer as Buffer$1 } from 'buffer';
 import { transform } from 'sucrase';
 import http$1 from 'http';
 import https$1 from 'https';
@@ -3181,6 +3182,291 @@ function readableError(error) {
   }
 }
 
+/**
+ * The `Range` request header, for the one route that serves bytes a player
+ * seeks in: `/files`.
+ *
+ * A `<video>` element asks for ranges as a matter of course, and Safari will
+ * not play a video at all from a server that does not answer them. An HLS
+ * stream whose segments are byte ranges of one file (`#EXT-X-BYTERANGE`) asks
+ * for nothing else.
+ *
+ * Only a single range is honoured. A multi-range request (`bytes=0-1,5-6`) is
+ * answered with the whole file, which RFC 9110 permits, and nothing that plays
+ * media sends one. A header that does not parse is ignored the same way.
+ */
+
+function parseRangeHeader(header, size) {
+  if (!header) {
+    return {
+      kind: "none"
+    };
+  }
+  const match = /^\s*bytes\s*=\s*(.*)$/i.exec(header);
+  if (!match) {
+    return {
+      kind: "none"
+    };
+  }
+  const spec = match[1].trim();
+  if (spec.includes(",")) {
+    return {
+      kind: "none"
+    };
+  }
+  const suffix = /^-(\d+)$/.exec(spec);
+  if (suffix) {
+    const length = Number(suffix[1]);
+    if (length === 0 || size === 0) {
+      return {
+        kind: "unsatisfiable"
+      };
+    }
+    return {
+      kind: "range",
+      start: Math.max(0, size - length),
+      end: size - 1
+    };
+  }
+  const bounded = /^(\d+)-(\d*)$/.exec(spec);
+  if (!bounded) {
+    return {
+      kind: "none"
+    };
+  }
+  const start = Number(bounded[1]);
+  const end = bounded[2] === "" ? undefined : Number(bounded[2]);
+  if (end !== undefined && end < start) {
+    // Syntactically invalid (RFC 9110 §14.1.1): ignored, not refused.
+    return {
+      kind: "none"
+    };
+  }
+  if (start >= size) {
+    return {
+      kind: "unsatisfiable"
+    };
+  }
+  return {
+    kind: "range",
+    start,
+    end: Math.min(end ?? size - 1, size - 1)
+  };
+}
+
+/**
+ * The little of HLS (RFC 8216) the server has to read: the variants of a
+ * master playlist, the segment durations of a media playlist, and every URI a
+ * playlist names.
+ *
+ * Deliberately a line scanner rather than a parser. The playlists Val reads are
+ * the ones the Studio wrote, and the questions asked of them are small — "how
+ * big is the largest rendition", "how long is it", "where does each URI
+ * point" — so a full model of the format would be code nothing exercises.
+ */
+
+/** One `#EXT-X-STREAM-INF` entry of a master playlist. */
+
+/** Lines of a playlist, with Windows line endings tolerated. */
+function linesOf(text) {
+  return text.split(/\r?\n/);
+}
+
+/**
+ * The attributes of a tag, e.g. the part after `#EXT-X-STREAM-INF:`.
+ *
+ * Quoted values may contain commas (`CODECS="avc1.64001f,mp4a.40.2"`), which
+ * is why this is not a `split(",")`. Quotes are removed from the values.
+ */
+function parseHlsAttributes(list) {
+  const attributes = {};
+  const re = /([A-Z0-9-]+)=("[^"]*"|[^,]*)/g;
+  let match;
+  while ((match = re.exec(list)) !== null) {
+    const [, name, rawValue] = match;
+    attributes[name] = rawValue.startsWith('"') && rawValue.endsWith('"') ? rawValue.slice(1, -1) : rawValue.trim();
+  }
+  return attributes;
+}
+
+/** Whether a playlist is a master (multivariant) playlist. */
+function isHlsMasterPlaylist(text) {
+  return linesOf(text).some(line => line.trim().startsWith("#EXT-X-STREAM-INF:"));
+}
+
+/** The variants of a master playlist, in the order they are listed. */
+function parseHlsMasterVariants(text) {
+  const variants = [];
+  let pending = null;
+  for (const rawLine of linesOf(text)) {
+    const line = rawLine.trim();
+    if (line === "") {
+      continue;
+    }
+    if (line.startsWith("#EXT-X-STREAM-INF:")) {
+      const attributes = parseHlsAttributes(line.slice("#EXT-X-STREAM-INF:".length));
+      const variant = {};
+      const bandwidth = Number(attributes["BANDWIDTH"]);
+      if (attributes["BANDWIDTH"] !== undefined && Number.isFinite(bandwidth)) {
+        variant.bandwidth = bandwidth;
+      }
+      const resolution = /^(\d+)x(\d+)$/.exec(attributes["RESOLUTION"] ?? "");
+      if (resolution) {
+        variant.width = Number(resolution[1]);
+        variant.height = Number(resolution[2]);
+      }
+      pending = variant;
+      continue;
+    }
+    if (line.startsWith("#")) {
+      continue;
+    }
+    // The URI line that follows a STREAM-INF tag belongs to it.
+    if (pending) {
+      variants.push({
+        ...pending,
+        uri: line
+      });
+      pending = null;
+    }
+  }
+  return variants;
+}
+
+/**
+ * The variant whose dimensions describe the video: the largest picture, and
+ * among equally large ones the highest bandwidth. `undefined` when no variant
+ * declares a `RESOLUTION`.
+ */
+function largestHlsVariant(variants) {
+  let best;
+  for (const variant of variants) {
+    const {
+      width,
+      height
+    } = variant;
+    if (width === undefined || height === undefined) {
+      continue;
+    }
+    if (!best || width * height > best.width * best.height || width * height === best.width * best.height && (variant.bandwidth ?? 0) > (best.bandwidth ?? 0)) {
+      best = {
+        ...variant,
+        width,
+        height
+      };
+    }
+  }
+  return best;
+}
+
+/**
+ * The sum of a media playlist's `#EXTINF` durations, in seconds, or
+ * `undefined` when it has none (a master playlist, or not a playlist).
+ */
+function sumHlsSegmentDurations(text) {
+  let total = 0;
+  let found = false;
+  for (const rawLine of linesOf(text)) {
+    const line = rawLine.trim();
+    if (!line.startsWith("#EXTINF:")) {
+      continue;
+    }
+    const seconds = Number.parseFloat(line.slice("#EXTINF:".length));
+    if (Number.isFinite(seconds)) {
+      total += seconds;
+      found = true;
+    }
+  }
+  return found ? total : undefined;
+}
+
+/**
+ * Rewrite every URI a playlist names, leaving everything else byte for byte.
+ *
+ * URIs are the non-comment lines (segments, variant playlists) and the `URI`
+ * attribute of tags such as `#EXT-X-MAP` and `#EXT-X-MEDIA`. Line endings are
+ * kept as they were.
+ */
+function mapHlsUris(text, map) {
+  return text.split(/(\r?\n)/).map(part => {
+    if (part === "\n" || part === "\r\n") {
+      return part;
+    }
+    const trimmed = part.trim();
+    if (trimmed === "") {
+      return part;
+    }
+    if (trimmed.startsWith("#")) {
+      // Only an attribute that is exactly `URI` — preceded by the tag's
+      // colon or a comma — and not, say, a `KEYFORMAT-URI` lookalike.
+      return part.replace(/([:,]\s*)URI="([^"]*)"/g, (_match, before, uri) => `${before}URI="${map(uri)}"`);
+    }
+    const leading = part.slice(0, part.indexOf(trimmed));
+    const trailing = part.slice(part.indexOf(trimmed) + trimmed.length);
+    return `${leading}${map(trimmed)}${trailing}`;
+  }).join("");
+}
+
+/**
+ * An HLS playlist served as a DRAFT, with every URI in it pointed at the draft
+ * endpoint.
+ *
+ * Why this exists: a draft is served from `/api/val/files<path>?patch_id=…`,
+ * and a player resolves the playlist's URIs against that URL. A RELATIVE URI
+ * (`720p.m3u8`, how a local stream is written so it works wherever the
+ * directory is served from) resolves to `/api/val/files/public/val/x/720p.m3u8`
+ * — the query string is dropped by URL resolution, so the `patch_id` is gone,
+ * and the endpoint looks for a PUBLISHED file that does not exist yet. An
+ * ABSOLUTE remote ref (how a remote stream is written, because the content host
+ * addresses files by hash) points at the content host, which has nothing until
+ * publish. Either way the master plays and nothing it names does.
+ *
+ * So each URI is rewritten to the URL `Internal.mediaUrl` gives the same file
+ * as a draft. Every file of one upload is in the same patch, so they share the
+ * `patch_id` the playlist itself was requested with.
+ *
+ * What is NOT rewritten, and why:
+ * - an absolute URL that is not a Val remote ref (another host's stream): it
+ *   was never in a patch;
+ * - a root-relative URI (`/val/x/720p.mp4`): the Studio never writes one, and
+ *   it already names a published URL, so it is not this function's to guess at.
+ *
+ * Pure, and the whole rule: the `/files` route calls it and nothing else.
+ */
+function rewriteDraftPlaylist(playlist, options) {
+  return mapHlsUris(playlist, uri => rewriteUri(uri, options));
+}
+function rewriteUri(uri, {
+  playlistPath,
+  patchId,
+  remote
+}) {
+  if (Internal.remote.splitRemoteRef(uri).status === "success") {
+    return Internal.mediaUrl({
+      path: uri,
+      patch_id: patchId
+    });
+  }
+  if (/^[a-z][a-z0-9+.-]*:/i.test(uri) || uri.startsWith("/")) {
+    // Another scheme (https:, data:, …), protocol-relative or root-relative.
+    return uri;
+  }
+  // The query and fragment of a relative URI address the published file; the
+  // draft endpoint has its own query, and fragments do not reach a server.
+  const relative = uri.split(/[?#]/)[0];
+  if (relative === "") {
+    return uri;
+  }
+  // `join` from an absolute directory stays absolute: `..` stops at the root.
+  const resolved = path__default.posix.join(path__default.posix.dirname(playlistPath), relative);
+  return `/api/val/files${resolved}?patch_id=${patchId}${remote ? "&remote=true" : ""}`;
+}
+
+/** Whether a served file is an HLS playlist, by its extension. */
+function isHlsPlaylistPath(filePath) {
+  return filePath.split("?")[0].toLowerCase().endsWith(".m3u8");
+}
+
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const jsonOps = new JSONOps();
 /**
@@ -4004,9 +4290,20 @@ class ValOps {
                 // when constructing the url we use the patch id (and the file path)
                 // to fetch the right file
                 // NOTE: overwrite and use last patch_id if multiple patches modify the same file
-                fileFixOps[op.path.join("/")] = [{
+                //
+                // Keyed by where the patch_id LANDS — the field's path plus
+                // `nestedFilePath` — not by the field's path alone. A video's
+                // poster and caption files are file ops on the video's own path
+                // with `nestedFilePath` ["poster"] / ["captions", "0"]; keyed by
+                // `op.path` they overwrote the video's entry (and each other),
+                // so only one of the files got a patch_id and the rest were
+                // looked for at a published URL that holds nothing. JSON rather
+                // than a "/" join because a segment can contain "/" (a gallery
+                // key is a file path).
+                const patchIdPath = op.path.concat(...(op.nestedFilePath || [])).concat("patch_id");
+                fileFixOps[JSON.stringify(patchIdPath)] = [{
                   op: "add",
-                  path: op.path.concat(...(op.nestedFilePath || [])).concat("patch_id"),
+                  path: patchIdPath,
                   value: patchId
                 }];
               }
@@ -4204,7 +4501,7 @@ class ValOps {
         };
         if (validationErrors) {
           for (const validationError of validationErrors) {
-            var _validationError$fixe, _validationError$fixe2, _validationError$fixe3, _validationError$fixe4, _validationError$fixe5, _validationError$fixe6;
+            var _validationError$fixe, _validationError$fixe2, _validationError$fixe3, _validationError$fixe4, _validationError$fixe5, _validationError$fixe6, _validationError$fixe7, _validationError$fixe8;
             if (isOnlyFileCheckValidationError(validationError)) {
               if (files[sourcePath]) {
                 addError({
@@ -4224,7 +4521,7 @@ class ValOps {
                 addError(resolved.error);
               }
               // resolved.status === "resolved" → drop silently
-            } else if ((_validationError$fixe3 = validationError.fixes) !== null && _validationError$fixe3 !== void 0 && _validationError$fixe3.includes("images:check-unique-folder") || (_validationError$fixe4 = validationError.fixes) !== null && _validationError$fixe4 !== void 0 && _validationError$fixe4.includes("files:check-unique-folder")) {
+            } else if ((_validationError$fixe3 = validationError.fixes) !== null && _validationError$fixe3 !== void 0 && _validationError$fixe3.includes("images:check-unique-folder") || (_validationError$fixe4 = validationError.fixes) !== null && _validationError$fixe4 !== void 0 && _validationError$fixe4.includes("files:check-unique-folder") || (_validationError$fixe5 = validationError.fixes) !== null && _validationError$fixe5 !== void 0 && _validationError$fixe5.includes("videos:check-unique-folder")) {
               const TYPE_ERROR_MESSAGE = `This is most likely a Val version mismatch or Val bug.`;
               if (!validationError.value || typeof validationError.value !== "object") {
                 addError({
@@ -4249,7 +4546,7 @@ class ValOps {
                   // If conflictingModules is empty, directory is unique — silently drop the error.
                 }
               }
-            } else if ((_validationError$fixe5 = validationError.fixes) !== null && _validationError$fixe5 !== void 0 && _validationError$fixe5.includes("images:check-all-files") || (_validationError$fixe6 = validationError.fixes) !== null && _validationError$fixe6 !== void 0 && _validationError$fixe6.includes("files:check-all-files")) ; else {
+            } else if ((_validationError$fixe6 = validationError.fixes) !== null && _validationError$fixe6 !== void 0 && _validationError$fixe6.includes("images:check-all-files") || (_validationError$fixe7 = validationError.fixes) !== null && _validationError$fixe7 !== void 0 && _validationError$fixe7.includes("files:check-all-files") || (_validationError$fixe8 = validationError.fixes) !== null && _validationError$fixe8 !== void 0 && _validationError$fixe8.includes("videos:check-all-files")) ; else {
               addError(validationError);
             }
           }
@@ -5354,6 +5651,19 @@ class ValOps {
   async saveBinaryFileFromPatch(filePath, parentRef, patchId, bytes, mimeType, type, metadata) {
     return this.saveBase64EncodedBinaryFileFromPatch(filePath, parentRef, patchId, `data:${mimeType};base64,${bytes.toString("base64")}`, type, metadata);
   }
+  /**
+   * 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.
+   */
+  async openBinaryFile(filePath, fromPatch) {
+    const buffer = fromPatch ? await this.getBase64EncodedBinaryFileFromPatch(filePath, fromPatch.patchId, fromPatch.remote) : await this.getBinaryFile(filePath);
+    return buffer === null ? null : bufferReader(buffer);
+  }
 
   // #region history
   //
@@ -5404,8 +5714,8 @@ class ValOps {
   // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
-  var _validationError$fixe7;
-  if ((_validationError$fixe7 = validationError.fixes) !== null && _validationError$fixe7 !== void 0 && _validationError$fixe7.every(f => f === "file:check-metadata" || f === "image:check-metadata")) {
+  var _validationError$fixe9;
+  if ((_validationError$fixe9 = validationError.fixes) !== null && _validationError$fixe9 !== void 0 && _validationError$fixe9.every(f => f === "file:check-metadata" || f === "image:check-metadata")) {
     return true;
   }
   return false;
@@ -5595,6 +5905,15 @@ function bufferFromDataUrl(dataUrl) {
   }
 }
 
+/** A file of known size whose bytes are read a range at a time. */
+
+function bufferReader(buffer) {
+  return {
+    size: buffer.length,
+    read: async (start, end) => buffer.subarray(start, end + 1)
+  };
+}
+
 /**
  * The `*.val.json` files backing a `.jsonValues()` module's entries, as paths
  * relative to the project root.
@@ -8029,6 +8348,26 @@ class ValOpsFS extends ValOps {
       errors
     };
   }
+  async openBinaryFile(filePath, fromPatch) {
+    let absPath;
+    if (fromPatch) {
+      const patchesDir = this.getPatchesDir();
+      absPath = this.wherePatchFileIs(patchBinaryFile(patchesDir, fromPatch.patchId, filePath), stagedPatchBinaryFile(patchesDir, fromPatch.patchId, filePath));
+    } else {
+      absPath = path__default.join(this.rootDir, ...filePath.split("/"));
+      if (!this.host.fileExists(absPath)) {
+        absPath = null;
+      }
+    }
+    if (absPath === null) {
+      return null;
+    }
+    const path = absPath;
+    return {
+      size: this.host.binaryFileSize(path),
+      read: async (start, end) => this.host.readBinaryFileRange(path, start, end)
+    };
+  }
   async getBinaryFile(filePath) {
     const absPath = path__default.join(this.rootDir, ...filePath.split("/"));
     if (!this.host.fileExists(absPath)) {
@@ -8151,6 +8490,30 @@ class FSOpsHost {
   readBinaryFile(path) {
     return fs.readFileSync(path);
   }
+  binaryFileSize(path) {
+    return fs.statSync(path).size;
+  }
+
+  /** Bytes `start` to `end` inclusive, and only those, read off disk. */
+  async readBinaryFileRange(path, start, end) {
+    const handle = await fs.promises.open(path, "r");
+    try {
+      const buffer = Buffer$1.alloc(Math.max(0, end - start + 1));
+      let filled = 0;
+      while (filled < buffer.length) {
+        const {
+          bytesRead
+        } = await handle.read(buffer, filled, buffer.length - filled, start + filled);
+        if (bytesRead === 0) {
+          break;
+        }
+        filled += bytesRead;
+      }
+      return buffer.subarray(0, filled);
+    } finally {
+      await handle.close();
+    }
+  }
   readUtf8File(path) {
     return fs.readFileSync(path, "utf-8");
   }
@@ -8452,6 +8815,8 @@ const GetApplicablePatches = z.object({
    * Optional for the same reason.
    */
   headVersion: z.number().optional(),
+  /** Of `patches`, the ones a running publish holds. See `OrderedPatches.publishingPatches`. */
+  publishingPatches: z.array(PatchId$1).optional(),
   commits: z.array(z.object({
     commitSha: z.string(),
     /*
@@ -9336,6 +9701,13 @@ class ValOpsHttp extends ValOps {
       deployments: allPatchData.deployments || [],
       patches,
       appliedPatches,
+      /*
+       * Absent, not empty, from a content service that does not say: an empty
+       * list would claim no publish is running when it cannot know.
+       */
+      ...(allPatchData.publishingPatches !== undefined ? {
+        publishingPatches: allPatchData.publishingPatches
+      } : {}),
       /*
        * The CHAIN head, not the publish head below. Spread: absent is a content
        * service that does not report it, which is not the same as `null`.
@@ -9703,6 +10075,9 @@ class ValOpsHttp extends ValOps {
             } : {}),
             ...(data.headVersion !== undefined ? {
               headVersion: data.headVersion
+            } : {}),
+            ...(data.publishingPatches !== undefined ? {
+              publishingPatches: data.publishingPatches
             } : {})
           };
         }
@@ -12280,6 +12655,15 @@ const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
  */
 const VAL_APP_ENV = "app";
 
+/**
+ * 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.
+ */
+const APP_MODE_REQUIRES_REMOTE_FILES = "This project runs in the Val app, which stores every image, file and " + "video on Val's remote content host -- there is no repository for an " + "upload to go into. Add `files: { remote: true }` to `initVal` in " + "val.config.ts, so that `s.image()`, `s.file()`, `s.video()` and the " + "sets are remote everywhere this project is read. Images already in the " + "project then fail validation until they are uploaded: `npx val validate " + "--fix` does that.";
+
 /** Which mode the environment SAYS this is, and which variable said so. */
 
 /**
@@ -12426,7 +12810,7 @@ async function initHandlerOptions(route, opts, config) {
     valContentUrl
   });
   if (isProxyMode) {
-    var _opts$versions, _opts$versions2;
+    var _config$files, _opts$versions, _opts$versions2;
     /*
      * Why this app is in http mode, in the message that says what is missing.
      *
@@ -12479,6 +12863,27 @@ async function initHandlerOptions(route, opts, config) {
     if (!maybeValProject) {
       throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
     }
+    /*
+     * The Val app has no repository for an uploaded file to go into, so every
+     * image, file and video in it is remote -- and the project has to SAY so,
+     * in `val.config.ts`, rather than this server deciding it.
+     *
+     * Deciding it here would be easy and wrong. The schemas are built when
+     * `val.config.ts` and the modules are evaluated, before this function
+     * sees anything, and the same file is evaluated by `val validate`, the VS
+     * Code extension and `pnpm dev`. A switch only the app could see would
+     * leave every one of those reading the project's media as local: every
+     * remote image reported as a mistake, and `val validate --fix` downloading
+     * it back into the repository.
+     *
+     * So this refuses rather than covers for it. Without the check, the
+     * failure is quieter and later: a local upload that the app has nowhere
+     * to put, found at a publish.
+     */
+    // `config?.`: `initVal()` with no argument hands back no config at all.
+    if (isAppEnv && (config === null || config === void 0 || (_config$files = config.files) === null || _config$files === void 0 ? void 0 : _config$files.remote) !== true) {
+      throw new Error(APP_MODE_REQUIRES_REMOTE_FILES);
+    }
     const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
     if (!coreVersion) {
       throw new Error("Could not determine version of @valbuild/core");
@@ -12811,6 +13216,12 @@ async function resolveRemoteFileAuth(options) {
 
 /** What a publish reports back, in either shape. */
 
+/**
+ * Where a local file a publish commits is written. Fixed: it was configurable
+ * (`files.directory` in val.config.ts), nobody configured it, and the schemas
+ * have their own `dir` for any collection that wants somewhere else.
+ */
+const FILES_DIRECTORY = "/public/val";
 const ValServer = (valModules, options, callbacks) => {
   var _options$git;
   const AIContentBlock = z.union([z.object({
@@ -14827,7 +15238,6 @@ const ValServer = (valModules, options, callbacks) => {
     },
     "/publish-job-prepare": {
       POST: async req => {
-        var _options$config$files2;
         const auth = getAuth(req.cookies);
         if (auth.error) {
           return {
@@ -14874,7 +15284,6 @@ const ValServer = (valModules, options, callbacks) => {
          * push either way.
          */
         if (serverOps.sourceMode() === "connected") {
-          var _options$config$files;
           const jobPatches = await serverOps.fetchPatches({
             patchIds,
             excludePatchOps: false
@@ -14927,7 +15336,7 @@ const ValServer = (valModules, options, callbacks) => {
           const deploymentFiles = commit === undefined ? await serverOps.embeddedValSourceShas() : null;
           const sent = await serverOps.prepareJob(jobId, {
             tab,
-            filesDirectory: ((_options$config$files = options.config.files) === null || _options$config$files === void 0 ? void 0 : _options$config$files.directory) || "/public/val",
+            filesDirectory: FILES_DIRECTORY,
             ...split.archive,
             ...(commit !== undefined ? {
               gitCommit: commit
@@ -14956,7 +15365,7 @@ const ValServer = (valModules, options, callbacks) => {
         } = built;
         const sent = await serverOps.prepareJob(jobId, {
           tab,
-          filesDirectory: ((_options$config$files2 = options.config.files) === null || _options$config$files2 === void 0 ? void 0 : _options$config$files2.directory) || "/public/val",
+          filesDirectory: FILES_DIRECTORY,
           ...split.archive
         });
         return jobPrepareAnswer(sent, {
@@ -15444,17 +15853,14 @@ const ValServer = (valModules, options, callbacks) => {
              */
             const managedBranch = serverOps.sourceMode() === "managed" ? serverOps.projectBranch() : null;
             const committedBinaries = serverOps.sourceMode() === "managed" ? await readCommittedBinaryFiles(serverOps, preparedCommit.patchedBinaryFilesDescriptors) : null;
-            const commitToGit = () => {
-              var _options$config$files3;
-              return serverOps.commit(preparedCommit, message, auth.id, ((_options$config$files3 = options.config.files) === null || _options$config$files3 === void 0 ? void 0 : _options$config$files3.directory) || "/public/val", undefined,
-              /*
-               * Forwarded verbatim, and only the client can decide it: the
-               * content API closes the group it is named without checking
-               * that the commit shipped all of it, and whether it did needs
-               * the patch sets, which live in the browser.
-               */
-              body.patchGroupId);
-            };
+            const commitToGit = () => serverOps.commit(preparedCommit, message, auth.id, FILES_DIRECTORY, undefined,
+            /*
+             * Forwarded verbatim, and only the client can decide it: the
+             * content API closes the group it is named without checking
+             * that the commit shipped all of it, and whether it did needs
+             * the patch sets, which live in the browser.
+             */
+            body.patchGroupId);
             /*
              * A host may publish somewhere other than the repository.
              *
@@ -16441,34 +16847,18 @@ const ValServer = (valModules, options, callbacks) => {
         // nothing fetches it backend-to-backend. Neither half of the argument
         // above transfers. See architecture/media.md, "Why /files has no auth,
         // and /history/files does".
-        let fileBuffer;
-        let mimeType;
         const remote = query.remote === "true";
-        if (query.patch_id) {
-          fileBuffer = await serverOps.getBase64EncodedBinaryFileFromPatch(filePath, query.patch_id, remote);
-          mimeType = Internal.filenameToMimeType(filePath);
-        } else {
-          if (serverOps instanceof ValOpsHttp && remote) {
-            console.error(`Remote file: ${filePath} requested without patch id. This is most likely a bug in Val.`);
-          }
-          fileBuffer = await serverOps.getBinaryFile(filePath);
+        const patchId = query.patch_id;
+        if (!patchId && serverOps instanceof ValOpsHttp && remote) {
+          console.error(`Remote file: ${filePath} requested without patch id. This is most likely a bug in Val.`);
         }
-        if (fileBuffer) {
-          return {
-            status: 200,
-            headers: {
-              // TODO: we could use ETag and return 304 instead
-              "Content-Type": mimeType || "application/octet-stream",
-              // TODO: a file requested with a patch_id is immutable for that
-              // patch, so it could be served "public, max-age=20000, immutable"
-              // instead. There used to be a `cacheControl` variable here for
-              // that, but its only assignment was commented out, so every
-              // response has always taken the revalidate branch.
-              "Cache-Control": "public, max-age=0, must-revalidate"
-            },
-            body: bufferToReadableStream(fileBuffer)
-          };
-        } else {
+        // Opened, not read: a video is seeked in by many small ranges, and
+        // only the asked-for bytes are read where the mode can (fs).
+        const opened = await serverOps.openBinaryFile(filePath, patchId ? {
+          patchId: patchId,
+          remote
+        } : null);
+        if (!opened) {
           return {
             status: 404,
             json: {
@@ -16476,6 +16866,62 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
+        // A DRAFT playlist names files that are drafts too, at URLs that only
+        // resolve once published. See `rewriteDraftPlaylist`. Playlists are
+        // small, so one is read whole to be rewritten.
+        const file = patchId && isHlsPlaylistPath(filePath) ? bufferReader(Buffer.from(rewriteDraftPlaylist((await opened.read(0, opened.size - 1)).toString("utf-8"), {
+          playlistPath: filePath,
+          patchId,
+          remote
+        }), "utf-8")) : opened;
+        const headers = {
+          // TODO: we could use ETag and return 304 instead
+          // From the extension, published or draft: a `<video>` and an HLS
+          // player both decide what they are holding by it, and it used to be
+          // set for drafts only.
+          "Content-Type": Internal.filenameToMimeType(filePath) || "application/octet-stream",
+          // TODO: a file requested with a patch_id is immutable for that
+          // patch, so it could be served "public, max-age=20000, immutable"
+          // instead. There used to be a `cacheControl` variable here for
+          // that, but its only assignment was commented out, so every
+          // response has always taken the revalidate branch.
+          "Cache-Control": "public, max-age=0, must-revalidate",
+          "Accept-Ranges": "bytes"
+        };
+        const range = parseRangeHeader(req.headers.range, file.size);
+        if (range.kind === "unsatisfiable") {
+          return {
+            status: 416,
+            headers: {
+              ...headers,
+              "Content-Range": `bytes */${file.size}`
+            },
+            json: {
+              message: `Range not satisfiable: ${req.headers.range}`
+            }
+          };
+        }
+        if (range.kind === "range") {
+          const slice = await file.read(range.start, range.end);
+          return {
+            status: 206,
+            headers: {
+              ...headers,
+              "Content-Range": `bytes ${range.start}-${range.end}/${file.size}`,
+              "Content-Length": String(slice.length)
+            },
+            body: bufferToReadableStream(slice)
+          };
+        }
+        const body = file.size === 0 ? Buffer.alloc(0) : await file.read(0, file.size - 1);
+        return {
+          status: 200,
+          headers: {
+            ...headers,
+            "Content-Length": String(body.length)
+          },
+          body: bufferToReadableStream(body)
+        };
       }
     }
   };
@@ -17823,301 +18269,2692 @@ class ValFSHost {
   }
 }
 
-async function extractImageMetadata(filename, input) {
-  const imageSize = sizeOf(new Uint8Array(input));
-  let mimeType = null;
-  if (imageSize.type) {
-    const possibleMimeType = `image/${imageSize.type}`;
-    if (Internal.MIME_TYPES_TO_EXT[possibleMimeType]) {
-      mimeType = possibleMimeType;
-    }
-    const filenameBasedLookup = Internal.filenameToMimeType(filename);
-    if (filenameBasedLookup) {
-      mimeType = filenameBasedLookup;
-    }
-  }
-  if (!mimeType) {
-    mimeType = "application/octet-stream";
-  }
-  let {
-    width,
-    height
-  } = imageSize;
-  if (!width || !height) {
-    width = 0;
-    height = 0;
-  }
+/**
+ * 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. */
+
+function bufferByteSource(buffer) {
   return {
-    width,
-    height,
-    mimeType
+    size: buffer.length,
+    read: (offset, length) => buffer.subarray(offset, offset + length)
   };
 }
-async function extractFileMetadata(filename, _input // TODO: use buffer to determine mimetype
-) {
-  let mimeType = Internal.filenameToMimeType(filename);
-  if (!mimeType) {
-    mimeType = "application/octet-stream";
+
+/**
+ * Run `read` against a file on disk, reading only what it asks for. The file
+ * is closed afterwards whatever happens.
+ */
+function withFileByteSource(absolutePath, read) {
+  const fd = fs.openSync(absolutePath, "r");
+  try {
+    const size = fs.fstatSync(fd).size;
+    return read({
+      size,
+      read: (offset, length) => {
+        const wanted = Math.max(0, Math.min(length, size - offset));
+        const buffer = Buffer.alloc(wanted);
+        let filled = 0;
+        while (filled < wanted) {
+          const n = fs.readSync(fd, buffer, filled, wanted - filled, offset + filled);
+          if (n === 0) {
+            break;
+          }
+          filled += n;
+        }
+        return buffer.subarray(0, filled);
+      }
+    });
+  } finally {
+    fs.closeSync(fd);
   }
-  return {
-    mimeType
-  };
 }
-
 /**
- * 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.
+ * A `moov` larger than this is not a header worth reading into memory. A
+ * two-hour film's is a few MB; this is far past any real one.
  */
+const MAX_MOOV_SIZE = 64 * 1024 * 1024;
 
 /**
- * A key that names somewhere else, whether or not it is a ref we can read.
- *
- * Case-insensitive, because a scheme is (RFC 3986) — and because
- * `splitRemoteRef`'s pattern is not, so `HTTPS://…` is precisely one of the
- * spellings that arrives here unparsed and must not be mistaken for a path.
+ * 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.
  */
-function isRemoteUrl(key) {
-  return /^https?:\/\//i.test(key);
-}
-function galleryEntryOf(key) {
-  const remoteRefRes = Internal.remote.splitRemoteRef(key);
+function readIsoBmffMetadata(source) {
+  const moov = findTopLevelBox(source, "moov");
+  if (!moov) {
+    return {};
+  }
+  const metadata = {};
+  const mvhd = childBox(moov, "mvhd");
+  const timescaleAndDuration = mvhd ? readMvhd(mvhd) : undefined;
+  if (timescaleAndDuration) {
+    const {
+      timescale,
+      duration
+    } = timescaleAndDuration;
+    if (duration > 0) {
+      metadata.duration = duration / timescale;
+    } else {
+      // A fragmented file (CMAF) says 0 in mvhd and puts the length in mehd,
+      // in the same timescale.
+      const mehd = childBox(childBox(moov, "mvex"), "mehd");
+      const fragmentDuration = mehd ? readMehd(mehd) : undefined;
+      if (fragmentDuration !== undefined && fragmentDuration > 0) {
+        metadata.duration = fragmentDuration / timescale;
+      }
+    }
+  }
+  for (const trak of childBoxes(moov, "trak")) {
+    const hdlr = childBox(childBox(trak, "mdia"), "hdlr");
+    if (!hdlr || hdlr.length < 12 || hdlr.toString("latin1", 8, 12) !== "vide") {
+      continue;
+    }
+    const tkhd = childBox(trak, "tkhd");
+    const size = tkhd ? readTkhd(tkhd) : undefined;
+    if (size && size.width > 0 && size.height > 0) {
+      metadata.width = size.width;
+      metadata.height = size.height;
+      break;
+    }
+  }
+  return metadata;
+}
+
+/** The payload (after the header) of the first top-level box of a type. */
+function findTopLevelBox(source, type) {
+  let offset = 0;
+  while (offset + 8 <= source.size) {
+    const header = source.read(offset, 16);
+    if (header.length < 8) {
+      return undefined;
+    }
+    let size = header.readUInt32BE(0);
+    const boxType = header.toString("latin1", 4, 8);
+    let headerSize = 8;
+    if (size === 1) {
+      if (header.length < 16) {
+        return undefined;
+      }
+      size = Number(header.readBigUInt64BE(8));
+      headerSize = 16;
+    } else if (size === 0) {
+      size = source.size - offset;
+    }
+    if (size < headerSize) {
+      return undefined;
+    }
+    if (boxType === type) {
+      if (size - headerSize > MAX_MOOV_SIZE) {
+        return undefined;
+      }
+      const payload = source.read(offset + headerSize, size - headerSize);
+      return payload.length === size - headerSize ? payload : undefined;
+    }
+    offset += size;
+  }
+  return undefined;
+}
+
+/** Each child box of a container payload, as `[type, payload]`. */
+function* boxesIn(payload) {
+  let offset = 0;
+  while (offset + 8 <= payload.length) {
+    let size = payload.readUInt32BE(offset);
+    const type = payload.toString("latin1", offset + 4, offset + 8);
+    let headerSize = 8;
+    if (size === 1) {
+      if (offset + 16 > payload.length) {
+        return;
+      }
+      size = Number(payload.readBigUInt64BE(offset + 8));
+      headerSize = 16;
+    } else if (size === 0) {
+      size = payload.length - offset;
+    }
+    if (size < headerSize || offset + size > payload.length) {
+      return;
+    }
+    yield [type, payload.subarray(offset + headerSize, offset + size)];
+    offset += size;
+  }
+}
+function childBoxes(payload, type) {
+  if (!payload) {
+    return [];
+  }
+  const found = [];
+  for (const [boxType, child] of boxesIn(payload)) {
+    if (boxType === type) {
+      found.push(child);
+    }
+  }
+  return found;
+}
+function childBox(payload, type) {
+  return childBoxes(payload, type)[0];
+}
+
+/** "Unknown" in a version 1 box. Not a literal: `0x…n` needs an ES2020 target. */
+const ALL_ONES_64 = BigInt("0xffffffffffffffff");
+function readMvhd(mvhd) {
+  const version = mvhd[0];
+  if (version === 1) {
+    if (mvhd.length < 32) return undefined;
+    const timescale = mvhd.readUInt32BE(20);
+    const duration = mvhd.readBigUInt64BE(24);
+    if (timescale === 0 || duration === ALL_ONES_64) {
+      return undefined;
+    }
+    return {
+      timescale,
+      duration: Number(duration)
+    };
+  }
+  if (mvhd.length < 20) return undefined;
+  const timescale = mvhd.readUInt32BE(12);
+  const duration = mvhd.readUInt32BE(16);
+  // All ones means "unknown" in a version 0 box.
+  if (timescale === 0 || duration === 0xffffffff) {
+    return undefined;
+  }
+  return {
+    timescale,
+    duration
+  };
+}
+function readMehd(mehd) {
+  if (mehd[0] === 1) {
+    return mehd.length >= 12 ? Number(mehd.readBigUInt64BE(4)) : undefined;
+  }
+  return mehd.length >= 8 ? mehd.readUInt32BE(4) : undefined;
+}
+
+/**
+ * The size a track is SHOWN at: tkhd's width and height, swapped when the
+ * display matrix turns the picture a quarter turn — a phone records upright
+ * video sideways and says so here, and a page lays it out as it is shown.
+ */
+function readTkhd(tkhd) {
+  // Past the version-specific times and ids, then 16 bytes of reserved,
+  // layer, alternate group, volume and reserved, then the 36-byte matrix.
+  const matrixAt = tkhd[0] === 1 ? 4 + 32 + 16 : 4 + 20 + 16;
+  const widthAt = matrixAt + 36;
+  if (tkhd.length < widthAt + 8) {
+    return undefined;
+  }
+  const a = tkhd.readInt32BE(matrixAt);
+  const b = tkhd.readInt32BE(matrixAt + 4);
+  const c = tkhd.readInt32BE(matrixAt + 12);
+  const d = tkhd.readInt32BE(matrixAt + 16);
+  const width = Math.round(tkhd.readUInt32BE(widthAt) / 0x10000);
+  const height = Math.round(tkhd.readUInt32BE(widthAt + 4) / 0x10000);
+  const quarterTurn = a === 0 && d === 0 && b !== 0 && c !== 0;
+  return quarterTurn ? {
+    width: height,
+    height: width
+  } : {
+    width,
+    height
+  };
+}
+
+/**
+ * The size and length of a Matroska file (`.webm`, and `.mkv`, which is the
+ * same container), read from its headers. Nothing is decoded.
+ *
+ * Hand-written for the same reason `isoBmff.ts` is: `@valbuild/server` is
+ * loaded by every app that runs Val, and what is wanted here is a handful of
+ * integers two levels into the file:
+ *
+ *   EBML                          the header; a file without one is not Matroska
+ *   Segment > Info                TimecodeScale and Duration
+ *   Segment > Tracks > TrackEntry TrackType 1 (video) >
+ *     Video                       PixelWidth / PixelHeight, and DisplayWidth /
+ *                                 DisplayHeight when they are in pixels
+ *
+ * Matroska is EBML: every element is a variable-length ID, a variable-length
+ * size and a payload. Only element HEADERS are read on the way through the
+ * Segment, and then the payloads of Info and Tracks, which are a few hundred
+ * bytes. The Clusters — the frames, which are the file — are never read: the
+ * walk stops at the first one.
+ *
+ * That is allowed because the spec (RFC 9559, section 6.3) requires the first
+ * Info and Tracks to come before the first Cluster, or to be named by a
+ * SeekHead that does. A file written by a browser's MediaRecorder, or by
+ * anything else that streams, does not know its own length when it starts:
+ * its Segment and Clusters have the "unknown" size, and its Info has no
+ * Duration. The Segment is then read as running to the end of the file, and
+ * the duration is left out rather than counted from the Clusters — a caller
+ * reports it, as it does for a fragmented mp4.
+ */
+
+const EBML_HEADER = 0x1a45dfa3;
+const SEGMENT = 0x18538067;
+const SEEK_HEAD = 0x114d9b74;
+const SEEK = 0x4dbb;
+const SEEK_ID = 0x53ab;
+const SEEK_POSITION = 0x53ac;
+const INFO = 0x1549a966;
+const TIMECODE_SCALE = 0x2ad7b1;
+const DURATION = 0x4489;
+const TRACKS = 0x1654ae6b;
+const TRACK_ENTRY = 0xae;
+const TRACK_TYPE = 0x83;
+const VIDEO = 0xe0;
+const PIXEL_WIDTH = 0xb0;
+const PIXEL_HEIGHT = 0xba;
+const DISPLAY_WIDTH = 0x54b0;
+const DISPLAY_HEIGHT = 0x54ba;
+const DISPLAY_UNIT = 0x54b2;
+const CLUSTER = 0x1f43b675;
+const TRACK_TYPE_VIDEO = 1;
+const DISPLAY_UNIT_PIXELS = 0;
+/** Nanoseconds per tick, when Info does not say. */
+const DEFAULT_TIMECODE_SCALE = 1_000_000;
+
+/**
+ * Info, Tracks or a SeekHead larger than this is not a header worth reading
+ * into memory. Tracks is the big one, for its codec private data, and that is
+ * kilobytes.
+ */
+const MAX_HEADER_ELEMENT_SIZE = 16 * 1024 * 1024;
+
+/**
+ * Whatever of {@link EbmlMetadata} the file declares. A field that cannot be
+ * read is absent; nothing here throws on a file that is not Matroska.
+ */
+function readEbmlMetadata(source) {
+  const header = readElementHeader(source, 0);
+  if (!header || header.id !== EBML_HEADER || header.size === undefined) {
+    return {};
+  }
+  const segment = findSegment(source, header.dataStart + header.size);
+  if (!segment) {
+    return {};
+  }
+  const segmentStart = segment.dataStart;
+  const segmentEnd = segment.size === undefined ? source.size : Math.min(source.size, segmentStart + segment.size);
+  let info;
+  let tracks;
+  const seekPositions = new Map();
+  let offset = segmentStart;
+  while (offset < segmentEnd && !(info && tracks)) {
+    const element = readElementHeader(source, offset);
+    if (!element || element.id === CLUSTER) {
+      break;
+    }
+    if (element.id === INFO && !info) {
+      info = readPayload(source, element);
+    } else if (element.id === TRACKS && !tracks) {
+      tracks = readPayload(source, element);
+    } else if (element.id === SEEK_HEAD) {
+      const seekHead = readPayload(source, element);
+      if (seekHead) {
+        readSeekHead(seekHead, seekPositions);
+      }
+    }
+    if (element.size === undefined) {
+      // Only a Segment or a Cluster may have an unknown size, and an element
+      // whose end is unknown cannot be stepped over.
+      break;
+    }
+    offset = element.dataStart + element.size;
+  }
+  // Not before the first Cluster: the SeekHead says where.
+  if (!info) {
+    info = readSought(source, segmentStart, seekPositions, INFO);
+  }
+  if (!tracks) {
+    tracks = readSought(source, segmentStart, seekPositions, TRACKS);
+  }
+  const metadata = {};
+  const duration = info ? readDuration(info) : undefined;
+  if (duration !== undefined) {
+    metadata.duration = duration;
+  }
+  const size = tracks ? readVideoSize(tracks) : undefined;
+  if (size) {
+    metadata.width = size.width;
+    metadata.height = size.height;
+  }
+  return metadata;
+}
+/** The first Segment among the top-level elements after the EBML header. */
+function findSegment(source, from) {
+  let offset = from;
+  while (offset < source.size) {
+    const element = readElementHeader(source, offset);
+    if (!element) {
+      return undefined;
+    }
+    if (element.id === SEGMENT) {
+      return element;
+    }
+    if (element.size === undefined) {
+      return undefined;
+    }
+    offset = element.dataStart + element.size;
+  }
+  return undefined;
+}
+function readElementHeader(source, offset) {
+  // At most 4 bytes of ID and 8 of size.
+  const bytes = source.read(offset, 12);
+  const id = readVint(bytes, 0, 4);
+  if (!id) {
+    return undefined;
+  }
+  const size = readVint(bytes, id.length, 8);
+  if (!size) {
+    return undefined;
+  }
+  return {
+    id: id.raw,
+    size: size.unknown ? undefined : size.value,
+    dataStart: offset + id.length + size.length
+  };
+}
+function readPayload(source, element) {
+  const {
+    size
+  } = element;
+  if (size === undefined || size > MAX_HEADER_ELEMENT_SIZE) {
+    return undefined;
+  }
+  const payload = source.read(element.dataStart, size);
+  return payload.length === size ? payload : undefined;
+}
+/**
+ * An EBML variable-length integer: the number of leading zero bits of the
+ * first byte, plus one, is its length in bytes. Built with arithmetic rather
+ * than shifts, which are 32-bit and signed in JavaScript.
+ */
+function readVint(bytes, offset, maxLength) {
+  if (offset >= bytes.length) {
+    return undefined;
+  }
+  const first = bytes[offset];
+  if (first === 0) {
+    return undefined;
+  }
+  const length = Math.clz32(first) - 23;
+  if (length > maxLength || offset + length > bytes.length) {
+    return undefined;
+  }
+  const valueMask = 0xff >> length;
+  let raw = first;
+  let value = first & valueMask;
+  let unknown = value === valueMask;
+  for (let i = 1; i < length; i++) {
+    const byte = bytes[offset + i];
+    raw = raw * 256 + byte;
+    value = value * 256 + byte;
+    unknown = unknown && byte === 0xff;
+  }
+  return {
+    length,
+    raw,
+    value,
+    unknown
+  };
+}
+
+/** Each child element of a master element's payload, as `[id, payload]`. */
+function* elementsIn(payload) {
+  let offset = 0;
+  while (offset < payload.length) {
+    const id = readVint(payload, offset, 4);
+    if (!id) {
+      return;
+    }
+    const size = readVint(payload, offset + id.length, 8);
+    if (!size || size.unknown) {
+      return;
+    }
+    const dataStart = offset + id.length + size.length;
+    const end = dataStart + size.value;
+    if (end > payload.length) {
+      return;
+    }
+    yield [id.raw, payload.subarray(dataStart, end)];
+    offset = end;
+  }
+}
+function child(payload, id) {
+  for (const [childId, data] of elementsIn(payload)) {
+    if (childId === id) {
+      return data;
+    }
+  }
+  return undefined;
+}
+function readUint(data) {
+  if (!data || data.length > 8) {
+    return undefined;
+  }
+  let value = 0;
+  for (const byte of data) {
+    value = value * 256 + byte;
+  }
+  return value;
+}
+function readFloat(data) {
+  if ((data === null || data === void 0 ? void 0 : data.length) === 4) {
+    return data.readFloatBE(0);
+  }
+  if ((data === null || data === void 0 ? void 0 : data.length) === 8) {
+    return data.readDoubleBE(0);
+  }
+  return undefined;
+}
+
+/** Where each top-level element a SeekHead names is, from the Segment's data. */
+function readSeekHead(seekHead, into) {
+  for (const [id, seek] of elementsIn(seekHead)) {
+    if (id !== SEEK) {
+      continue;
+    }
+    const seekId = child(seek, SEEK_ID);
+    const position = readUint(child(seek, SEEK_POSITION));
+    if (seekId && seekId.length <= 4 && position !== undefined) {
+      const target = readUint(seekId);
+      if (target !== undefined && !into.has(target)) {
+        into.set(target, position);
+      }
+    }
+  }
+}
+function readSought(source, segmentStart, seekPositions, id) {
+  const position = seekPositions.get(id);
+  if (position === undefined) {
+    return undefined;
+  }
+  const element = readElementHeader(source, segmentStart + position);
+  return (element === null || element === void 0 ? void 0 : element.id) === id ? readPayload(source, element) : undefined;
+}
+
+/**
+ * Info's Duration is a float in ticks of TimecodeScale nanoseconds. Absent in
+ * a file written as it was recorded, and then absent here too.
+ */
+function readDuration(info) {
+  const duration = readFloat(child(info, DURATION));
+  if (duration === undefined || !Number.isFinite(duration) || duration <= 0) {
+    return undefined;
+  }
+  const scale = readUint(child(info, TIMECODE_SCALE)) ?? DEFAULT_TIMECODE_SCALE;
+  if (scale <= 0) {
+    return undefined;
+  }
+  return duration * scale / 1e9;
+}
+
+/**
+ * The size the first video track is SHOWN at. DisplayWidth and DisplayHeight
+ * are what a non-square-pixel (anamorphic) video is laid out at, so they win
+ * over the stored PixelWidth and PixelHeight — but only when DisplayUnit says
+ * they are pixels. The other units (centimetres, inches, a bare aspect ratio)
+ * are not a size a page can use, so the pixel size is reported instead.
+ */
+function readVideoSize(tracks) {
+  for (const [id, entry] of elementsIn(tracks)) {
+    if (id !== TRACK_ENTRY || readUint(child(entry, TRACK_TYPE)) !== TRACK_TYPE_VIDEO) {
+      continue;
+    }
+    const video = child(entry, VIDEO);
+    if (!video) {
+      continue;
+    }
+    const pixelWidth = readUint(child(video, PIXEL_WIDTH));
+    const pixelHeight = readUint(child(video, PIXEL_HEIGHT));
+    const displayUnit = readUint(child(video, DISPLAY_UNIT)) ?? DISPLAY_UNIT_PIXELS;
+    if (displayUnit === DISPLAY_UNIT_PIXELS) {
+      const displayWidth = readUint(child(video, DISPLAY_WIDTH));
+      const displayHeight = readUint(child(video, DISPLAY_HEIGHT));
+      if (displayWidth && displayHeight) {
+        return {
+          width: displayWidth,
+          height: displayHeight
+        };
+      }
+    }
+    if (pixelWidth && pixelHeight) {
+      return {
+        width: pixelWidth,
+        height: pixelHeight
+      };
+    }
+  }
+  return undefined;
+}
+
+async function extractImageMetadata(filename, input) {
+  const imageSize = sizeOf(new Uint8Array(input));
+  let mimeType = null;
+  if (imageSize.type) {
+    const possibleMimeType = `image/${imageSize.type}`;
+    if (Internal.MIME_TYPES_TO_EXT[possibleMimeType]) {
+      mimeType = possibleMimeType;
+    }
+    const filenameBasedLookup = Internal.filenameToMimeType(filename);
+    if (filenameBasedLookup) {
+      mimeType = filenameBasedLookup;
+    }
+  }
+  if (!mimeType) {
+    mimeType = "application/octet-stream";
+  }
+  let {
+    width,
+    height
+  } = imageSize;
+  if (!width || !height) {
+    width = 0;
+    height = 0;
+  }
+  return {
+    width,
+    height,
+    mimeType
+  };
+}
+async function extractFileMetadata(filename, _input // TODO: use buffer to determine mimetype
+) {
+  let mimeType = Internal.filenameToMimeType(filename);
+  if (!mimeType) {
+    mimeType = "application/octet-stream";
+  }
+  return {
+    mimeType
+  };
+}
+
+/**
+ * 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.
+ */
+async function extractVideoMetadata(filename, input, readFile = readFileOrUndefined$2) {
+  if (isHlsPath(filename)) {
+    return extractHlsMetadata(filename, input.toString("utf-8"), readFile);
+  }
+  return extractFromByteSource(filename, bufferByteSource(input));
+}
+
+/**
+ * {@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.
+ */
+async function extractVideoMetadataFromFile(absolutePath) {
+  if (isHlsPath(absolutePath)) {
+    return extractVideoMetadata(absolutePath, fs.readFileSync(absolutePath));
+  }
+  return withFileByteSource(absolutePath, source => extractFromByteSource(absolutePath, source));
+}
+const ISO_BMFF_EXTENSIONS = [".mp4", ".m4v", ".mov"];
+const EBML_EXTENSIONS = [".webm", ".mkv"];
+
+/** The extensions whose size and length Val reads itself. */
+const READABLE_VIDEO_EXTENSIONS = [...ISO_BMFF_EXTENSIONS, ...EBML_EXTENSIONS, ".m3u8"];
+
+/**
+ * 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.
+ */
+function unreadableVideoMetadataMessage(fileRef, fields) {
+  const extension = extensionOf(fileRef);
+  if (!canReadVideoMetadata(fileRef)) {
+    return `Val cannot read the size and length of a ${extension || "file without an extension"} file on the command line. Upload it again in the Val Studio, or add ${listOf(fields)} by hand.`;
+  }
+  return `Val could not read the ${listOf(fields)} of ${fileRef}. Upload it again in the Val Studio, or add ${listOf(fields)} by hand.`;
+}
+
+/** Whether Val reads this video's size and length itself, by its extension. */
+function canReadVideoMetadata(fileRef) {
+  return READABLE_VIDEO_EXTENSIONS.includes(extensionOf(fileRef));
+}
+function extensionOf(fileRef) {
+  return path__default.extname(fileRef.split("?")[0]).toLowerCase();
+}
+function listOf(fields) {
+  return fields.length <= 1 ? fields.join("") : `${fields.slice(0, -1).join(", ")} and ${fields[fields.length - 1]}`;
+}
+function isHlsPath(filename) {
+  return path__default.extname(filename).toLowerCase() === ".m3u8";
+}
+function extractFromByteSource(filename, source) {
+  const metadata = {};
+  const mimeType = Internal.filenameToMimeType(filename);
+  if (mimeType) {
+    metadata.mimeType = mimeType;
+  }
+  const extension = extensionOf(filename);
+  const read = ISO_BMFF_EXTENSIONS.includes(extension) ? readIsoBmffMetadata(source) : EBML_EXTENSIONS.includes(extension) ? readEbmlMetadata(source) : undefined;
+  if (!read) {
+    return metadata;
+  }
+  if (read.width !== undefined && read.height !== undefined) {
+    metadata.width = read.width;
+    metadata.height = read.height;
+  }
+  const duration = roundSeconds(read.duration);
+  if (duration !== undefined) {
+    metadata.duration = duration;
+  }
+  return metadata;
+}
+
+/**
+ * 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.
+ */
+async function readHlsMetadata(text, readMediaPlaylist) {
+  const metadata = {
+    mimeType: Internal.media.HLS_MIME_TYPE
+  };
+  if (!isHlsMasterPlaylist(text)) {
+    // A media playlist on its own: it knows how long it is, not how big.
+    const duration = roundSeconds(sumHlsSegmentDurations(text));
+    if (duration !== undefined) {
+      metadata.duration = duration;
+    }
+    return metadata;
+  }
+  const variants = parseHlsMasterVariants(text);
+  const largest = largestHlsVariant(variants);
+  if (largest) {
+    metadata.width = largest.width;
+    metadata.height = largest.height;
+  }
+  // Every rendition is the same length, so the first one listed is as good as
+  // any.
+  const first = variants[0];
+  if (first) {
+    const mediaPlaylist = await readMediaPlaylist(first.uri);
+    if (mediaPlaylist !== undefined) {
+      const duration = roundSeconds(sumHlsSegmentDurations(mediaPlaylist));
+      if (duration !== undefined) {
+        metadata.duration = duration;
+      }
+    }
+  }
+  return metadata;
+}
+function extractHlsMetadata(filename, text, readFile) {
+  // Only a relative URI can be read from disk: the Studio writes relative
+  // URIs into a local stream.
+  return readHlsMetadata(text, async uri => {
+    var _readFile;
+    return isRelativeUri(uri) ? (_readFile = readFile(path__default.resolve(path__default.dirname(filename), uri.split(/[?#]/)[0]))) === null || _readFile === void 0 ? void 0 : _readFile.toString("utf-8") : undefined;
+  });
+}
+function isRelativeUri(uri) {
+  return !/^[a-z][a-z0-9+.-]*:/i.test(uri) && !uri.startsWith("/");
+}
+
+/**
+ * Seconds to the millisecond. A duration summed from `#EXTINF`s or computed
+ * from timestamps carries float noise (`5.999999999`), and this value is
+ * written into a `.val.ts` someone reads.
+ */
+function roundSeconds(seconds) {
+  if (seconds === undefined || !Number.isFinite(seconds) || seconds <= 0) {
+    return undefined;
+  }
+  return Math.round(seconds * 1000) / 1000;
+}
+function readFileOrUndefined$2(absolutePath) {
+  try {
+    return fs.readFileSync(absolutePath);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A remote video's size and length, read over HTTP without downloading it.
+ *
+ * The parsers (`isoBmff.ts`, `ebml.ts`) are synchronous and ask a
+ * {@link ByteSource} for the few header bytes they need. Here that source is
+ * a cache of byte ranges fetched with `Range` requests: when the parser asks
+ * for bytes the cache does not hold, the read throws {@link NeedBytes}, the
+ * missing range is fetched, and the parser runs again from the start. Parsing
+ * headers is microseconds and fetching is milliseconds, so re-running is the
+ * cheap side of that trade — and it keeps ONE parser for files on disk and
+ * files on Val Remote, rather than an async copy of each.
+ *
+ * An mp4 with `moov` first costs one request; one with `moov` after `mdat`
+ * costs about three (the start, the box header past `mdat`, and `moov`
+ * itself), however large the file. An HLS stream is its master playlist and
+ * one media playlist.
+ */
+
+/** How much to fetch past what was asked for: box headers come in runs. */
+const READ_AHEAD = 64 * 1024;
+/** A parser that needs more fetches than this is not reading headers. */
+const MAX_FETCHES = 16;
+/** Thrown by a cached read that needs bytes not fetched yet. */
+class NeedBytes {
+  constructor(offset, length) {
+    this.offset = offset;
+    this.length = length;
+  }
+}
+
+/**
+ * Read `url`'s metadata. `nameForType` is the file name its type is read off —
+ * for a remote ref, the `/public/...` path inside it, since the ref's own URL
+ * ends in the same name but is not where a reader would look for it.
+ */
+async function extractVideoMetadataFromUrl(url, nameForType, fetchImpl = fetch) {
+  if (nameForType.split("?")[0].toLowerCase().endsWith(".m3u8")) {
+    const master = await fetchText(url, fetchImpl);
+    return readHlsMetadata(master, uri => fetchText(new URL(uri, url).toString(), fetchImpl).catch(() => undefined));
+  }
+  const cache = new RangeCache(url, fetchImpl);
+  for (let fetches = 0;; fetches++) {
+    const source = await cache.source();
+    try {
+      return extractFromByteSource(nameForType, source);
+    } catch (err) {
+      if (!(err instanceof NeedBytes)) {
+        throw err;
+      }
+      if (fetches >= MAX_FETCHES) {
+        throw new Error(`Reading the headers of ${url} took more than ${MAX_FETCHES} requests`, {
+          cause: err
+        });
+      }
+      await cache.fetch(err.offset, err.length);
+    }
+  }
+}
+
+/** The local `/public/...` path a remote ref names, for its file type. */
+function nameForTypeOf(ref) {
+  const split = Internal.remote.splitRemoteRef(ref);
+  return split.status === "success" ? `/${split.filePath}` : ref;
+}
+async function fetchText(url, fetchImpl) {
+  const res = await fetchImpl(url, {
+    headers: {}
+  });
+  if (!res.ok) {
+    throw new Error(`Could not read ${url}: HTTP ${res.status}`);
+  }
+  return res.text();
+}
+class RangeCache {
+  /** Fetched ranges, as [start, bytes]. Few, so a list is enough. */
+  chunks = [];
+  size;
+  constructor(url, fetchImpl) {
+    this.url = url;
+    this.fetchImpl = fetchImpl;
+  }
+
+  /** A source over what is cached, after fetching the start if nothing is. */
+  async source() {
+    if (this.size === undefined) {
+      await this.fetch(0, READ_AHEAD);
+    }
+    const size = this.size ?? 0;
+    return {
+      size,
+      read: (offset, length) => {
+        const end = Math.min(offset + length, size);
+        if (end <= offset) {
+          return Buffer.alloc(0);
+        }
+        for (const [start, bytes] of this.chunks) {
+          if (start <= offset && end <= start + bytes.length) {
+            return bytes.subarray(offset - start, end - start);
+          }
+        }
+        throw new NeedBytes(offset, end - offset);
+      }
+    };
+  }
+  async fetch(offset, length) {
+    const last = offset + Math.max(length, READ_AHEAD) - 1;
+    const res = await this.fetchImpl(this.url, {
+      headers: {
+        Range: `bytes=${offset}-${last}`
+      }
+    });
+    if (res.status === 200) {
+      // The server ignored the range and sent the whole file. That answers
+      // every read there will be.
+      const whole = Buffer.from(await res.arrayBuffer());
+      this.chunks = [[0, whole]];
+      this.size = whole.length;
+      return;
+    }
+    if (res.status !== 206) {
+      throw new Error(`Could not read ${this.url}: HTTP ${res.status}`);
+    }
+    // `bytes 0-65535/1234567`: where the bytes start, and how big the file is.
+    const range = /^bytes (\d+)-(\d+)\/(\d+|\*)$/.exec(res.headers.get("content-range") ?? "");
+    if (!range) {
+      throw new Error(`Could not read ${this.url}: a partial answer without a Content-Range`);
+    }
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (range[3] !== "*") {
+      this.size = Number(range[3]);
+    } else if (this.size === undefined) {
+      throw new Error(`Could not read ${this.url}: its size is not known`);
+    }
+    this.chunks.push([Number(range[1]), bytes]);
+  }
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * A key that names somewhere else, whether or not it is a ref we can read.
+ *
+ * Case-insensitive, because a scheme is (RFC 3986) — and because
+ * `splitRemoteRef`'s pattern is not, so `HTTPS://…` is precisely one of the
+ * spellings that arrives here unparsed and must not be mistaken for a path.
+ */
+function isRemoteUrl(key) {
+  return /^https?:\/\//i.test(key);
+}
+function galleryEntryOf(key) {
+  const remoteRefRes = Internal.remote.splitRemoteRef(key);
   if (remoteRefRes.status === "success") {
     return {
-      localPath: `/${remoteRefRes.filePath}`,
-      remote: true
+      localPath: `/${remoteRefRes.filePath}`,
+      remote: true
+    };
+  }
+  if (isRemoteUrl(key)) {
+    // A URL that is not a ref this version can read: truncated by a hand edit,
+    // a path outside `public/`, a `..` segment — or written by a core version
+    // whose format `splitRemoteRef` rejects.
+    //
+    // Still not a path in the working tree, so the on-disk checks must not run
+    // against it. They would find nothing at `<projectRoot>/https://…`, report
+    // the entry as missing, and `--fix` would DELETE it — the exact failure
+    // this module exists to prevent, arriving at the one moment the key is the
+    // only remaining record of where the bytes went.
+    //
+    // Nothing is being hidden by this: a malformed key is already reported, by
+    // the record schema's own "Invalid remote URL format". That is an error for
+    // a person to look at, not a file for `--fix` to go missing.
+    return {
+      localPath: key,
+      remote: true
+    };
+  }
+  return {
+    localPath: key,
+    remote: false
+  };
+}
+
+/**
+ * The media path a validation error is about, if it is about media at all.
+ *
+ * There is no schema in hand here — a `ValidationError` carries only the value
+ * it flagged — so the shape is all there is to go on.
+ */
+function getValidationErrorFileRef(validationError) {
+  const maybePath = validationError.value && typeof validationError.value === "object" && "path" in validationError.value && typeof validationError.value.path === "string" ? validationError.value.path : undefined;
+  if (!maybePath) {
+    return null;
+  }
+  return maybePath;
+}
+
+const textEncoder$1 = new TextEncoder();
+async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
+  const remoteRefDataRes = Internal.remote.splitRemoteRef(ref);
+  if (remoteRefDataRes.status === "error") {
+    return remoteRefDataRes;
+  }
+  const fileHash = remoteRefDataRes.fileHash;
+  if (!fileHash) {
+    return {
+      status: "error",
+      error: `File hash is missing in remote ref: ${ref}`
+    };
+  }
+  const relativeFilePath = remoteRefDataRes.filePath;
+  if (!relativeFilePath) {
+    return {
+      status: "error",
+      error: `File path is missing in remote ref: ${ref}`
+    };
+  }
+  if (!relativeFilePath.startsWith("public/")) {
+    return {
+      status: "error",
+      error: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
+    };
+  }
+  const coreVersion = Internal.VERSION.core || "unknown";
+  const fileExt = getFileExt(relativeFilePath);
+  const currentValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata,
+  // TODO: validate
+  fileHash, textEncoder$1);
+  const validationHashFromRemoteRefValues = Internal.remote.getValidationHash(remoteRefDataRes.version, schema, getFileExt(remoteRefDataRes.filePath), metadata,
+  // TODO: validate
+  fileHash, textEncoder$1);
+  if (
+  // Current validation hash is the same as the remote validation hash
+  // We assume the uploaded file exists and is correct
+  currentValidationHash === remoteRefDataRes.validationHash &&
+  // This can happen if the version or fileExt has been tampered with
+  // (or if the way it is computed has changed)
+  validationHashFromRemoteRefValues === remoteRefDataRes.validationHash) {
+    return {
+      status: "success"
+    };
+  }
+  // Validation hash does not match, so we need to re-validate the remote content
+  const fileBufferRes = await getFileBufferFromRemote(ref, fileExt, remoteRefDataRes.fileHash, projectRoot);
+
+  // We could not download the remote file for some reason (for example, the file hash is wrong)
+  if (fileBufferRes.status === "error") {
+    return fileBufferRes;
+  }
+
+  // At this point we have the file buffer and we know the correct file hash
+  // We must create a new ref since something has changed
+
+  let currentMetadata;
+  try {
+    if (schema.type === "image") {
+      currentMetadata = await extractImageMetadata(remoteRefDataRes.filePath, fileBufferRes.fileBuffer);
+    } else if (schema.type === "file") {
+      currentMetadata = await extractFileMetadata(remoteRefDataRes.filePath, fileBufferRes.fileBuffer);
+    } else {
+      const exhaustiveCheck = schema;
+      return {
+        status: "error",
+        error: `Unknown schema type: ${JSON.stringify(exhaustiveCheck)}`
+      };
+    }
+  } catch (err) {
+    return {
+      status: "error",
+      error: `Failed to extract metadata from remote file: ${err instanceof Error ? err.message : "Unknown error"}. Cached file: ${fileBufferRes.cachedFilePath}`
+    };
+  }
+  const updatedMetadata = {
+    ...metadata,
+    ...currentMetadata
+  };
+  const nextValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder$1);
+  if (!updatedMetadata.mimeType) {
+    return {
+      status: "error",
+      error: `MIME type is missing in metadata: ${JSON.stringify(updatedMetadata)}`
+    };
+  }
+  const newFileExt = Internal.mimeTypeToFileExt(updatedMetadata.mimeType);
+  const newFilePath = relativeFilePath.slice(0, -fileExt.length) + newFileExt;
+  return {
+    status: "fix-required",
+    metadata: updatedMetadata,
+    ref: Internal.remote.createRemoteRef(remoteHost, {
+      publicProjectId: remoteRefDataRes.projectId,
+      coreVersion,
+      bucket: remoteRefDataRes.bucket,
+      validationHash: nextValidationHash,
+      fileHash: fileBufferRes.fileHash,
+      filePath: newFilePath
+    })
+  };
+}
+function getCachedRemoteFileDir(projectRoot) {
+  // store in projectRoot/.val/remote-file-cache
+  const remoteFileCacheDir = path__default.join(projectRoot, ".val", "remote-file-cache");
+  return remoteFileCacheDir;
+}
+function getCachedRemoteFilePath(fileExt, currentFileHash, remoteFileCacheDir) {
+  const remoteFilePath = path__default.join(remoteFileCacheDir, currentFileHash + "." + fileExt);
+  return remoteFilePath;
+}
+async function getFileBufferFromRemote(ref, fileExt, currentFileHash, projectRoot) {
+  const remoteFileCacheDir = getCachedRemoteFileDir(projectRoot);
+  const remoteFilePath = getCachedRemoteFilePath(fileExt, currentFileHash, remoteFileCacheDir);
+  try {
+    const fileBuffer = await fs.promises.readFile(remoteFilePath);
+    const computedFileHash = Internal.remote.getFileHash(fileBuffer);
+    if (computedFileHash !== currentFileHash) {
+      await fs.promises.unlink(remoteFilePath);
+      throw Error(`Cached file hash does not match the expected hash: ${computedFileHash} !== ${currentFileHash}`);
+    }
+  } catch {
+    try {
+      await fs.promises.mkdir(remoteFileCacheDir, {
+        recursive: true
+      });
+      await downloadFileFromRemote(ref, remoteFilePath);
+    } catch (err) {
+      try {
+        // try to delete in case of partial download
+        await fs.promises.unlink(remoteFilePath);
+      } catch {
+        //
+      }
+      return {
+        status: "error",
+        error: `Failed to download remote file: ${err instanceof Error ? err.message : "Unknown error"}`
+      };
+    }
+  }
+  const fileBuffer = await fs.promises.readFile(remoteFilePath);
+  const computedFileHash = Internal.remote.getFileHash(fileBuffer);
+  return {
+    status: "success",
+    fileBuffer,
+    fileHash: computedFileHash,
+    cachedFilePath: remoteFilePath
+  };
+}
+async function downloadFileFromRemote(ref, filePath) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(ref);
+    const client = url.protocol === "https:" ? https$1 : http$1;
+    const request = client.get(url, response => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        // Handle redirects
+        return downloadFileFromRemote(response.headers.location, filePath).then(resolve).catch(reject);
+      }
+      if (response.statusCode == 404) {
+        return reject(new Error(`${ref}. File not found. The URL is most likely incorrect.`));
+      }
+      if (response.statusCode !== 200) {
+        return reject(new Error(`${ref}. Failed to download file. HTTP Status: ${response.statusCode}`));
+      }
+      const writeStream = fs.createWriteStream(filePath);
+      response.pipe(writeStream);
+      writeStream.on("finish", () => resolve({
+        status: "success",
+        filePath
+      }));
+      writeStream.on("error", err => reject(new Error(`${ref}. Error writing file: ${err.message}`)));
+    });
+    request.on("error", err => reject(new Error(`${ref}. Download error: ${err.message}`)));
+    request.end();
+  });
+}
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Everything an upload to Val Remote needs before it has any bytes: the
+ * developer's token, the project's public id and a bucket. Opened once per
+ * fix, so a video's dozen files go up under one session and into one bucket
+ * rather than a bucket each.
+ */
+
+async function openRemoteUploadSession(ctx) {
+  const fail = errorMessage => ({
+    success: false,
+    result: {
+      success: false,
+      errorMessage
+    }
+  });
+  const patFile = getPersonalAccessTokenPath(ctx.projectRoot);
+  if (!ctx.fs.fileExists(patFile)) {
+    return fail(`File: ${path__default.join(ctx.projectRoot, ctx.file)} has remote files that are not uploaded and you are not logged in.\n\nFix this error by logging in:\n\t"npx val login"\n`);
+  }
+  const patFileContent = ctx.fs.readFile(patFile);
+  if (patFileContent === undefined) {
+    return fail(`Could not read personal access token file at ${patFile}`);
+  }
+  const parsedPatFile = parsePersonalAccessTokenFile(patFileContent);
+  if (!parsedPatFile.success) {
+    return fail(`Error parsing personal access token file: ${parsedPatFile.error}. You need to login again.`);
+  }
+  const {
+    pat
+  } = parsedPatFile.data;
+  const projectName = ctx.project;
+  let publicProjectId = ctx.publicProjectId;
+  let remoteFileBuckets = ctx.remoteFileBuckets;
+  let remoteFilesCounter = ctx.remoteFilesCounter;
+  if (!publicProjectId || !remoteFileBuckets) {
+    if (!projectName) {
+      return fail("Project name not found. Add project name to val.config or set the VAL_PROJECT environment variable");
+    }
+    const settingsRes = await ctx.remote.getSettings(projectName, {
+      pat
+    });
+    if (!settingsRes.success) {
+      return fail(`Could not get public project id: ${settingsRes.message}.`);
+    }
+    publicProjectId = settingsRes.data.publicProjectId;
+    remoteFileBuckets = settingsRes.data.remoteFileBuckets.map(b => b.bucket);
+  }
+  if (!publicProjectId) {
+    return fail("Could not get public project id");
+  }
+  if (!projectName) {
+    return fail(`Could not get project. Check that your val.config has the 'project' field set, or set it using the VAL_PROJECT environment variable`);
+  }
+  remoteFilesCounter += 1;
+  const bucket = remoteFileBuckets[remoteFilesCounter % remoteFileBuckets.length];
+  if (!bucket) {
+    return fail(`Internal error: could not allocate a bucket for the remote file located at ${ctx.sourcePath}`);
+  }
+  return {
+    success: true,
+    session: {
+      pat,
+      projectName,
+      publicProjectId,
+      bucket,
+      remoteFileBuckets,
+      remoteFilesCounter
+    }
+  };
+}
+
+/**
+ * Upload one file's bytes and return the ref they are served at.
+ *
+ * `relativeFilePath` is the file's path under the project (`public/...`),
+ * which the ref encodes; the bytes need not be the bytes on disk there — a
+ * video's playlists are uploaded REWRITTEN, naming the refs of what they list.
+ */
+async function uploadBytesToRemote(ctx, session, relativeFilePath, fileBuffer, metadata, schema) {
+  if (!relativeFilePath.startsWith("public/")) {
+    return {
+      success: false,
+      error: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
+    };
+  }
+  const fileHash = Internal.remote.getFileHash(fileBuffer);
+  const coreVersion = Internal.VERSION.core || "unknown";
+  const fileExt = getFileExt(relativeFilePath);
+  const ref = Internal.remote.createRemoteRef(ctx.remote.remoteHost, {
+    publicProjectId: session.publicProjectId,
+    coreVersion,
+    bucket: session.bucket,
+    validationHash: Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata, fileHash, textEncoder),
+    fileHash,
+    filePath: relativeFilePath
+  });
+  const remoteFileUpload = await ctx.remote.uploadFile(session.projectName, session.bucket, fileHash, fileExt, fileBuffer, {
+    pat: session.pat
+  });
+  if (!remoteFileUpload.success) {
+    return {
+      success: false,
+      error: `Could not upload remote file: '${ref}'. Error: ${remoteFileUpload.error}`
+    };
+  }
+  return {
+    success: true,
+    ref
+  };
+}
+
+/**
+ * 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.
+ */
+function filesOfVideo(video, options) {
+  if (!isObject(video) || typeof video.path !== "string") {
+    return [];
+  }
+  const refs = new Set([video.path]);
+  if (isObject(video.poster) && typeof video.poster.path === "string") {
+    refs.add(video.poster.path);
+  }
+  if (Array.isArray(video.captions)) {
+    for (const track of video.captions) {
+      if (isObject(track) && typeof track.path === "string") {
+        refs.add(track.path);
+      }
+    }
+  }
+  const mimeType = typeof video.mimeType === "string" ? video.mimeType : undefined;
+  if (!Internal.isRemoteMediaPath(video.path) && Internal.media.isHlsVideo({
+    path: video.path,
+    mimeType
+  })) {
+    const readFile = options.readFile ?? readFileOrUndefined$1;
+    const pending = [video.path.split("?")[0]];
+    const visited = new Set();
+    while (pending.length > 0) {
+      var _readFile;
+      const playlist = pending.pop();
+      if (visited.has(playlist)) {
+        continue;
+      }
+      visited.add(playlist);
+      const text = (_readFile = readFile(path__default.join(options.projectRoot, ...playlist.split("/")))) === null || _readFile === void 0 ? void 0 : _readFile.toString("utf-8");
+      if (text === undefined) {
+        continue;
+      }
+      mapHlsUris(text, uri => {
+        const ref = localRefOf(uri, playlist);
+        if (ref !== undefined) {
+          refs.add(ref);
+          if (ref.toLowerCase().endsWith(".m3u8")) {
+            pending.push(ref);
+          }
+        }
+        return uri;
+      });
+    }
+  }
+  return [...refs];
+}
+
+/** A playlist URI as a local ref, when it is relative; otherwise undefined. */
+function localRefOf(uri, playlist) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(uri) || uri.startsWith("/")) {
+    return undefined;
+  }
+  const relative = uri.split(/[?#]/)[0];
+  if (relative === "") {
+    return undefined;
+  }
+  return path__default.posix.join(path__default.posix.dirname(playlist), relative);
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readFileOrUndefined$1(absolutePath) {
+  try {
+    return fs.readFileSync(absolutePath);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `video:upload-remote` and `video:download-remote`: move a video between the
+ * repository and Val Remote.
+ *
+ * A video is the one media value that names several files — the video, its
+ * poster, its caption tracks, and for an HLS stream every playlist and segment
+ * its master names — so one fix moves all of them, and the patch then rewrites
+ * every `path` the value holds. Moving only some would leave a video that is
+ * half on each side, which validation rejects and no page can play.
+ *
+ * HLS is the part that is not a copy. The content host serves a file by its
+ * HASH, so a relative name in a playlist resolves to nothing there: on the way
+ * UP every playlist is rewritten to name the refs of what it lists, bottom-up
+ * (a playlist's ref is the hash of its rewritten bytes, so what it names must
+ * be uploaded first). On the way DOWN the same playlists are rewritten back to
+ * relative names, which is what lets a published stream be plain static files.
+ */
+function isRecord$2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlaylist$1(ref) {
+  return ref.split("?")[0].toLowerCase().endsWith(".m3u8");
+}
+
+/** The paths a video value holds, each with where in the value it sits. */
+function videoPathsOf(video) {
+  if (!isRecord$2(video) || typeof video.path !== "string") {
+    return [];
+  }
+  const found = [{
+    at: ["path"],
+    path: video.path
+  }];
+  if (isRecord$2(video.poster) && typeof video.poster.path === "string") {
+    found.push({
+      at: ["poster", "path"],
+      path: video.poster.path
+    });
+  }
+  if (Array.isArray(video.captions)) {
+    video.captions.forEach((track, index) => {
+      if (isRecord$2(track) && typeof track.path === "string") {
+        found.push({
+          at: ["captions", String(index), "path"],
+          path: track.path
+        });
+      }
+    });
+  }
+  return found;
+}
+
+/**
+ * The patch that points a video at where its files now are: one `add` per
+ * path that moved, so the authored fields beside them — the description, the
+ * times, the caption labels — are never rewritten.
+ */
+function rewriteVideoPathsPatch(sourcePath, video, moved) {
+  const base = sourceToPatchPath(sourcePath);
+  const patch = [];
+  for (const {
+    at,
+    path: current
+  } of videoPathsOf(video)) {
+    const to = moved[current];
+    if (to !== undefined && to !== current) {
+      patch.push({
+        op: "add",
+        path: base.concat(at),
+        value: to
+      });
+    }
+  }
+  return patch;
+}
+
+/** A relative playlist URI as a `/public/...` ref, or undefined if it is not one. */
+function resolvePlaylistUri(uri, playlist) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(uri) || uri.startsWith("/")) {
+    return undefined;
+  }
+  const relative = uri.split(/[?#]/)[0];
+  if (relative === "") {
+    return undefined;
+  }
+  return path__default.posix.join(path__default.posix.dirname(playlist), relative);
+}
+function playlistUris(text) {
+  const uris = [];
+  mapHlsUris(text, uri => {
+    if (!uris.includes(uri)) uris.push(uri);
+    return uri;
+  });
+  return uris;
+}
+
+/** What a file is to the video that names it, which decides its hash basis. */
+
+/**
+ * What a file's validation hash is computed from — the same as the Studio
+ * computes for an upload (`createVideoPatch`), so a video moved by the CLI and
+ * one uploaded in the Studio carry refs of the same kind.
+ */
+function metadataOf(localRef, role, video) {
+  const mimeType = Internal.filenameToMimeType(localRef);
+  if (role === "video") {
+    return {
+      mimeType,
+      width: video.width,
+      height: video.height
+    };
+  }
+  if (role === "poster" && isRecord$2(video.poster)) {
+    return {
+      mimeType: video.poster.mimeType ?? mimeType,
+      width: video.poster.width,
+      height: video.poster.height
+    };
+  }
+  return {
+    mimeType
+  };
+}
+
+/**
+ * Places a video's local files on Val Remote, each once, and remembers where.
+ *
+ * The one implementation of "upload a video" for every fix that does it: a
+ * video field (`video:upload-remote`), and an entry of an `s.videoset()`
+ * (`videos:upload-remote`). What differs between the two is which files go up
+ * and what their refs are hashed against, so those are the arguments.
+ *
+ * A playlist goes up AFTER everything it names, rewritten to name their refs:
+ * the content host serves a file by its hash, so a relative name in a playlist
+ * resolves to nothing there — and a playlist's own ref is the hash of its
+ * rewritten bytes, so what it names must have refs first.
+ */
+function createVideoUploader(ctx, session, schema, metadataFor) {
+  const moved = new Map();
+  const events = [];
+  const put = async (localRef, role) => {
+    const already = moved.get(localRef);
+    if (already !== undefined) {
+      return already;
+    }
+    const absolute = path__default.join(ctx.projectRoot, localRef);
+    const buffer = ctx.fs.readBuffer(absolute);
+    if (buffer === undefined) {
+      throw new Error(`Error reading file: ${absolute}`);
+    }
+    let bytes = buffer;
+    if (isPlaylist$1(localRef)) {
+      // Bottom-up: what this playlist names goes up first, so the refs it is
+      // rewritten to exist — and so its own hash is of the rewritten bytes.
+      const text = buffer.toString("utf-8");
+      const refs = new Map();
+      for (const uri of playlistUris(text)) {
+        const target = resolvePlaylistUri(uri, localRef);
+        if (target !== undefined) {
+          refs.set(uri, await put(target, "stream"));
+        }
+      }
+      bytes = Buffer.from(mapHlsUris(text, uri => refs.get(uri) ?? uri), "utf-8");
+    }
+    const uploaded = await uploadBytesToRemote(ctx, session, localRef.replace(/^\//, ""), bytes, metadataFor(localRef, role), schema);
+    if (!uploaded.success) {
+      throw new Error(uploaded.error);
+    }
+    moved.set(localRef, uploaded.ref);
+    events.push({
+      type: "remote-uploaded",
+      ref: uploaded.ref
+    });
+    return uploaded.ref;
+  };
+  return {
+    put,
+    moved,
+    events
+  };
+}
+
+/**
+ * The first of `refs` — and of every file an HLS stream among them names —
+ * that is not on disk, as an absolute path.
+ *
+ * Asked before anything goes up: a missing segment found after the master's
+ * siblings were uploaded leaves bytes on the content host that nothing names.
+ */
+function firstMissingVideoFile(ctx, refs) {
+  for (const ref of refs) {
+    const files = filesOfVideo({
+      path: ref.path,
+      mimeType: ref.mimeType
+    }, {
+      projectRoot: ctx.projectRoot,
+      readFile: absolute => ctx.fs.readBuffer(absolute)
+    });
+    for (const file of files) {
+      const absolute = path__default.join(ctx.projectRoot, file);
+      if (!ctx.fs.fileExists(absolute)) {
+        return absolute;
+      }
+    }
+  }
+  return undefined;
+}
+function resolveVideo(ctx) {
+  var _resolved$schema;
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
+    return {
+      success: false,
+      result: {
+        success: false,
+        errorMessage: `Could not resolve source or schema for ${ctx.sourcePath}`
+      }
+    };
+  }
+  const resolved = Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema);
+  const video = resolved.source;
+  if (((_resolved$schema = resolved.schema) === null || _resolved$schema === void 0 ? void 0 : _resolved$schema.type) !== "video" || !isRecord$2(video) || typeof video.path !== "string") {
+    return {
+      success: false,
+      result: {
+        success: false,
+        errorMessage: `Expected a video at ${ctx.sourcePath}`
+      }
+    };
+  }
+  return {
+    success: true,
+    video,
+    schema: resolved.schema
+  };
+}
+
+/**
+ * The paths of a video FIELD that its fix moves.
+ *
+ * All of them for a video of its own. For a field picked from an
+ * `s.videoset()` (`referencedModule`), only the poster and the captions: the
+ * video file is the set's — its key there — and moving it from here would
+ * leave the field naming a file the set does not have. The set's own fix
+ * (`videos:upload-remote`) moves it, and rewrites the fields that name it.
+ */
+function movablePathsOf(video, schema) {
+  const setBacked = schema.referencedModule !== undefined;
+  return videoPathsOf(video).filter(({
+    at
+  }) => !setBacked || at[0] !== "path");
+}
+async function handleVideoUploadRemote(ctx) {
+  if (!ctx.fix) {
+    return {
+      success: false,
+      errorMessage: `Video needs to be uploaded to Val Remote (use --fix to upload)`
+    };
+  }
+  const resolved = resolveVideo(ctx);
+  if (!resolved.success) {
+    return resolved.result;
+  }
+  const {
+    video,
+    schema
+  } = resolved;
+  if (ctx.remoteFiles[ctx.sourcePath]) {
+    return {
+      success: true,
+      shouldApplyPatch: true,
+      events: [{
+        type: "remote-already-uploaded",
+        filePath: String(video.path)
+      }]
+    };
+  }
+  const toUpload = movablePathsOf(video, schema).filter(({
+    path: ref
+  }) => !Internal.isRemoteMediaPath(ref));
+  // Every file is checked before any goes up: a missing caption found after
+  // the video was uploaded leaves bytes on the content host that nothing names.
+  const missing = firstMissingVideoFile(ctx, toUpload.map(({
+    at,
+    path: ref
+  }) => ({
+    path: ref,
+    ...(at[0] === "path" && typeof video.mimeType === "string" ? {
+      mimeType: video.mimeType
+    } : {})
+  })));
+  if (missing !== undefined) {
+    return {
+      success: false,
+      errorMessage: `File ${missing} does not exist`
     };
   }
-  if (isRemoteUrl(key)) {
-    // A URL that is not a ref this version can read: truncated by a hand edit,
-    // a path outside `public/`, a `..` segment — or written by a core version
-    // whose format `splitRemoteRef` rejects.
-    //
-    // Still not a path in the working tree, so the on-disk checks must not run
-    // against it. They would find nothing at `<projectRoot>/https://…`, report
-    // the entry as missing, and `--fix` would DELETE it — the exact failure
-    // this module exists to prevent, arriving at the one moment the key is the
-    // only remaining record of where the bytes went.
-    //
-    // Nothing is being hidden by this: a malformed key is already reported, by
-    // the record schema's own "Invalid remote URL format". That is an error for
-    // a person to look at, not a file for `--fix` to go missing.
+  const opened = await openRemoteUploadSession(ctx);
+  if (!opened.success) {
+    return opened.result;
+  }
+  const {
+    session
+  } = opened;
+  const uploader = createVideoUploader(ctx, session, schema, (localRef, role) => metadataOf(localRef, role, video));
+  try {
+    for (const {
+      at,
+      path: ref
+    } of toUpload) {
+      await uploader.put(ref, at[0] === "poster" ? "poster" : at[0] === "captions" ? "caption" : "video");
+    }
+  } catch (err) {
+    return {
+      success: false,
+      errorMessage: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const refs = Object.fromEntries(uploader.moved);
+  ctx.remoteFiles[ctx.sourcePath] = {
+    ref: refs[String(video.path)] ?? String(video.path),
+    refs
+  };
+  return {
+    success: true,
+    shouldApplyPatch: true,
+    publicProjectId: session.publicProjectId,
+    remoteFileBuckets: session.remoteFileBuckets,
+    remoteFilesCounter: session.remoteFilesCounter,
+    events: uploader.events
+  };
+}
+async function handleVideoDownloadRemote(ctx) {
+  if (!ctx.fix) {
+    return {
+      success: false,
+      errorMessage: `Video ${ctx.sourcePath} needs to be downloaded (use --fix to download)`
+    };
+  }
+  const resolved = resolveVideo(ctx);
+  if (!resolved.success) {
+    return resolved.result;
+  }
+  const {
+    video,
+    schema
+  } = resolved;
+  const moved = new Map();
+  const fetchTo = async ref => {
+    const already = moved.get(ref);
+    if (already !== undefined) {
+      return already;
+    }
+    const split = Internal.remote.splitRemoteRef(ref);
+    if (split.status === "error") {
+      throw new Error(`Not a Val Remote ref: ${ref} (${split.error})`);
+    }
+    if (!split.filePath.startsWith("public/")) {
+      throw new Error(`Cannot download ${ref}: its file path must start with public/ (got ${split.filePath})`);
+    }
+    const localRef = `/${split.filePath}`;
+    const absolute = path__default.join(ctx.projectRoot, split.filePath);
+    await fs.promises.mkdir(path__default.dirname(absolute), {
+      recursive: true
+    });
+    const res = await downloadFileFromRemote(ref, absolute);
+    if (res.status === "error") {
+      throw new Error(res.error);
+    }
+    moved.set(ref, localRef);
+    if (isPlaylist$1(localRef)) {
+      // Back to relative names: a local stream is plain static files, and the
+      // draft endpoint rewrites relative names, not refs.
+      const text = fs.readFileSync(absolute, "utf-8");
+      const local = new Map();
+      for (const uri of playlistUris(text)) {
+        if (Internal.remote.splitRemoteRef(uri).status === "success") {
+          const target = await fetchTo(uri);
+          local.set(uri, path__default.posix.relative(path__default.posix.dirname(localRef), target));
+        }
+      }
+      fs.writeFileSync(absolute, mapHlsUris(text, uri => local.get(uri) ?? uri), "utf-8");
+    }
+    return localRef;
+  };
+  try {
+    for (const {
+      path: ref
+    } of movablePathsOf(video, schema)) {
+      if (Internal.isRemoteMediaPath(ref)) {
+        await fetchTo(ref);
+      }
+    }
+  } catch (err) {
+    return {
+      success: false,
+      errorMessage: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const refs = Object.fromEntries(moved);
+  ctx.remoteFiles[ctx.sourcePath] = {
+    ref: refs[String(video.path)] ?? String(video.path),
+    refs
+  };
+  return {
+    success: true,
+    shouldApplyPatch: true,
+    events: [{
+      type: "remote-downloading",
+      sourcePath: ctx.sourcePath
+    }]
+  };
+}
+
+/**
+ * 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.
+ */
+function checkGalleryFiles(input) {
+  const {
+    dir,
+    projectRoot,
+    fs,
+    filesOfEntry
+  } = input;
+  const entries = input.entryKeys.map(key => ({
+    key,
+    entry: galleryEntryOf(key)
+  }));
+  const trackedFiles = new Set();
+  for (const {
+    key,
+    entry
+  } of entries) {
+    trackedFiles.add(entry.localPath);
+    for (const file of (filesOfEntry === null || filesOfEntry === void 0 ? void 0 : filesOfEntry(entry, key)) ?? []) {
+      trackedFiles.add(file);
+    }
+  }
+  const missingTrackedFiles = entries.filter(({
+    entry
+  }) => !entry.remote && !fs.fileExists(path__default.join(projectRoot, entry.localPath))).map(({
+    entry
+  }) => entry.localPath);
+  return {
+    missingTrackedFiles,
+    untrackedFiles: filesInDirectory({
+      dir,
+      projectRoot,
+      fs
+    }).filter(f => !trackedFiles.has(f))
+  };
+}
+
+/**
+ * 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.
+ */
+function incompleteGalleryEntries(input) {
+  const exists = file => input.fs.fileExists(path__default.join(input.projectRoot, file));
+  const incomplete = [];
+  for (const key of input.entryKeys) {
+    const entry = galleryEntryOf(key);
+    if (entry.remote || !exists(entry.localPath)) {
+      continue;
+    }
+    const missing = input.filesOfEntry(entry, key).filter(file => file !== entry.localPath && !exists(file));
+    if (missing.length > 0) {
+      incomplete.push({
+        key,
+        missing
+      });
+    }
+  }
+  return incomplete;
+}
+
+/** Every file under `dir`, as `/public/…` refs; none for a directory not there. */
+function filesInDirectory({
+  dir,
+  projectRoot,
+  fs
+}) {
+  const filesInDir = [];
+  try {
+    const found = fs.readDirectory(path__default.join(projectRoot, dir), undefined, undefined, ["**/*"]);
+    for (const entry of found) {
+      filesInDir.push("/" + path__default.relative(projectRoot, entry).split(path__default.sep).join("/"));
+    }
+  } catch {
+    // directory doesn't exist — no untracked files possible
+  }
+  return filesInDir;
+}
+
+/**
+ * The fixes of an `s.videoset()` — the video twin of an image gallery.
+ *
+ * A set is a record keyed by each video's file path (an HLS stream by its
+ * master playlist), so most of this is the gallery fixes again with the key as
+ * the file. Three things are not, and they are why this is a module of its own
+ * rather than another branch in `fixHandlers.ts`:
+ *
+ * - **An entry is several files.** A stream's key is its master playlist, and
+ *   the media playlists and segments it names belong to the same entry. They
+ *   are tracked by it, uploaded with it, and none of them is an entry itself.
+ * - **The set's directory holds files that are not entries.** A field picked
+ *   from the set (`s.video(videosVal)`) keeps its own poster and caption
+ *   tracks, and the Studio puts them where the set keeps its videos. A file a
+ *   video field names is accounted for, not untracked.
+ * - **Fields elsewhere name an entry by its key.** Uploading an entry renames
+ *   its key to the remote ref, and every `s.video(videosVal)` whose `path` was
+ *   the old key would then name a video the set does not have. So the upload
+ *   rewrites them too (`otherModulePatches`).
+ *
+ * Nothing here imports `fixHandlers.ts` at runtime: that module registers
+ * these handlers, and a cycle would hand it undefined ones.
+ */
+
+/** The fields of a set entry that are read from the bytes, in the order written. */
+const VIDEO_METADATA_FIELDS$1 = ["mimeType", "width", "height", "duration"];
+
+/** What of a `Service` the project-wide walks need. */
+
+function isRecord$1(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlaylist(ref) {
+  return ref.split("?")[0].toLowerCase().endsWith(".m3u8");
+}
+function readFileOrUndefined(absolutePath) {
+  try {
+    return fs.readFileSync(absolutePath);
+  } catch {
+    return undefined;
+  }
+}
+
+/** See `Internal.videosetEntryVideoSchema`: the Studio hashes against it too. */
+function videosetEntryVideoSchema(record) {
+  return Internal.videosetEntryVideoSchema(record);
+}
+
+/** The key of the set entry at `sourcePath`: its last module path segment. */
+function entryKeyOf(sourcePath) {
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+  const parts = Internal.splitModulePath(modulePath);
+  return parts[parts.length - 1];
+}
+
+/**
+ * The patch path of `sourcePath`. Not `sourceToPatchPath`: a set's keys are
+ * file paths, and their dots do not survive its `split(".")`.
+ */
+function patchPathOf(sourcePath) {
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+  return Internal.splitModulePath(modulePath);
+}
+
+/**
+ * Every file a set entry holds: its key's file and, for an HLS stream, every
+ * playlist and segment its master names — read from the LOCAL copy, which a
+ * remote entry promoted by `--fix` still has, and which is the only place a
+ * stream's tree can be followed from at all.
+ */
+function filesOfVideosetEntry(entry, metadata, options) {
+  const fields = isRecord$1(metadata) ? metadata : {};
+  const mimeType = typeof fields.mimeType === "string" ? fields.mimeType : undefined;
+  // The entry's poster and captions are its defaults' files: the set holds
+  // them as it holds the video, so they are tracked by the entry — a remote
+  // one by the local path it was uploaded from, as the key is.
+  return filesOfVideo({
+    path: entry.localPath,
+    mimeType,
+    poster: fields.poster,
+    captions: fields.captions
+  }, options).map(ref => galleryEntryOf(ref).localPath);
+}
+
+/**
+ * An entry with every file it names that `moved` has a new ref for pointed
+ * at that ref: the poster and the captions, which a remote set keeps on the
+ * content host with the video.
+ */
+function withMovedFiles(entry, moved) {
+  const movedPath = file => isRecord$1(file) && typeof file.path === "string" && moved.has(file.path) ? {
+    ...file,
+    path: moved.get(file.path)
+  } : file;
+  return {
+    ...entry,
+    ...(entry.poster !== undefined ? {
+      poster: movedPath(entry.poster)
+    } : {}),
+    ...(Array.isArray(entry.captions) ? {
+      captions: entry.captions.map(movedPath)
+    } : {})
+  };
+}
+
+/** The entry's poster and caption files that are still local. */
+function localFilesOfEntry(entry) {
+  const files = [];
+  if (isRecord$1(entry.poster) && typeof entry.poster.path === "string") {
+    files.push({
+      path: entry.poster.path,
+      role: "poster"
+    });
+  }
+  if (Array.isArray(entry.captions)) {
+    for (const track of entry.captions) {
+      if (isRecord$1(track) && typeof track.path === "string") {
+        files.push({
+          path: track.path,
+          role: "caption"
+        });
+      }
+    }
+  }
+  return files.filter(file => !Internal.isRemoteMediaPath(file.path));
+}
+
+/**
+ * The untracked files of a set's directory, sorted into the ones `--fix` can
+ * make entries of and the ones a person has to decide about.
+ *
+ * - `videos`: an untracked stream (keyed by its master playlist — the media
+ *   playlists and segments it names are part of it and listed nowhere), and a
+ *   progressive video the set accepts.
+ * - `others`: everything else — a poster or caption no video field names, a
+ *   media playlist without a master, a video of a type the set does not
+ *   accept. `--fix` does not add these: none of them is a video the set could
+ *   hold, and deleting someone's file is not a fix.
+ */
+function classifyUntrackedVideosetFiles({
+  untracked,
+  accept,
+  projectRoot,
+  readFile = readFileOrUndefined
+}) {
+  const masters = untracked.filter(file => {
+    var _readFile;
+    if (!isPlaylist(file)) {
+      return false;
+    }
+    const text = (_readFile = readFile(path__default.join(projectRoot, file))) === null || _readFile === void 0 ? void 0 : _readFile.toString("utf-8");
+    return text !== undefined && isHlsMasterPlaylist(text);
+  });
+  const partOfAStream = new Set();
+  for (const master of masters) {
+    for (const file of filesOfVideo({
+      path: master
+    }, {
+      projectRoot,
+      readFile
+    })) {
+      if (file !== master) {
+        partOfAStream.add(file);
+      }
+    }
+  }
+  const videos = [];
+  const others = [];
+  for (const file of untracked) {
+    if (partOfAStream.has(file)) {
+      continue;
+    }
+    if (masters.includes(file)) {
+      videos.push(file);
+      continue;
+    }
+    const mimeType = Internal.filenameToMimeType(file);
+    if (mimeType !== undefined && mimeType.startsWith("video/") && Internal.mimeTypeMatchesAccept(mimeType, accept)) {
+      videos.push(file);
+    } else {
+      others.push(file);
+    }
+  }
+  return {
+    videos,
+    others
+  };
+}
+
+/** Whether a serialized schema has a video field anywhere in it. */
+function hasVideoField(schema) {
+  if (Array.isArray(schema)) {
+    return schema.some(hasVideoField);
+  }
+  if (!isRecord$1(schema)) {
+    return false;
+  }
+  if (schema.type === "video") {
+    return true;
+  }
+  return Object.values(schema).some(hasVideoField);
+}
+/**
+ * Every video field in the project, with its value.
+ *
+ * Validated reads for the modules that have one, because only those come back
+ * with their `.jsonValues()` entries loaded — an unvalidated read hands back
+ * each entry as a marker, and a field inside one would be invisible. Modules
+ * without a video are read once, unvalidated, to find that out.
+ */
+async function videoFieldsOf(service) {
+  const found = [];
+  for (const moduleFilePath of service.getModuleFilePaths()) {
+    const shallow = await service.get(moduleFilePath, "", {
+      validate: false
+    });
+    if (!hasVideoField(shallow.schema)) {
+      continue;
+    }
+    const loaded = await service.get(moduleFilePath, "", {
+      validate: true
+    });
+    if (loaded.source === undefined || !loaded.schema) {
+      continue;
+    }
+    traverseSchemaSource(loaded.source, loaded.schema, moduleFilePath, ({
+      source,
+      schema,
+      path: sourcePath
+    }) => {
+      if (schema.type === "video") {
+        found.push({
+          moduleFilePath,
+          sourcePath,
+          source,
+          schema
+        });
+      }
+    });
+  }
+  return found;
+}
+
+/**
+ * The files video fields name — a video of its own, and the poster and
+ * captions of every field — as `/public/…` refs, a remote one by the local
+ * path it was uploaded from.
+ */
+async function filesNamedByVideoFields(service, options) {
+  const files = new Set();
+  for (const field of await videoFieldsOf(service)) {
+    for (const ref of filesOfVideo(field.source, options)) {
+      // A remote ref by the path it encodes: `--fix` uploads a poster and
+      // leaves the file where it was, exactly as it does a set's entry, and
+      // that file is the field's — not something the set forgot.
+      files.add(galleryEntryOf(ref).localPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * The patches that point every `s.video(set)` field at a set entry's new key.
+ *
+ * One `add` on each field's `path`, so the description, poster, times and
+ * captions beside it are never rewritten. A field of another set, or of no
+ * set, is left alone even when its path is the same string: it names its own
+ * file.
+ */
+async function videosetReferencePatches(service, setModuleFilePath, renamed) {
+  const byModule = new Map();
+  for (const field of await videoFieldsOf(service)) {
+    if (field.schema.referencedModule !== setModuleFilePath) {
+      continue;
+    }
+    const value = field.source;
+    const current = isRecord$1(value) ? value.path : undefined;
+    if (typeof current !== "string" || !(current in renamed)) {
+      continue;
+    }
+    const patch = byModule.get(field.moduleFilePath) ?? [];
+    patch.push({
+      op: "add",
+      path: patchPathOf(field.sourcePath).concat("path"),
+      value: renamed[current]
+    });
+    byModule.set(field.moduleFilePath, patch);
+  }
+  return [...byModule].map(([moduleFilePath, patch]) => ({
+    moduleFilePath,
+    patch
+  }));
+}
+
+/** The record at `sourcePath` and its entries, or why it could not be read. */
+function resolveVideoset(module, sourcePath) {
+  var _resolved$schema;
+  if (module.source === undefined || !module.schema) {
+    return {
+      success: false,
+      errorMessage: `Could not resolve source or schema for ${sourcePath}`
+    };
+  }
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+  const resolved = Internal.resolvePath(modulePath, module.source, module.schema);
+  if (((_resolved$schema = resolved.schema) === null || _resolved$schema === void 0 ? void 0 : _resolved$schema.type) !== "record" || resolved.schema.mediaType !== "videos") {
+    var _resolved$schema2;
+    return {
+      success: false,
+      errorMessage: `Expected a video set at ${sourcePath}, got ${((_resolved$schema2 = resolved.schema) === null || _resolved$schema2 === void 0 ? void 0 : _resolved$schema2.type) ?? "nothing"}`
+    };
+  }
+  return {
+    success: true,
+    record: resolved.schema,
+    entries: isRecord$1(resolved.source) ? resolved.source : {}
+  };
+}
+
+/**
+ * `videos:add-metadata`: the entry's KEY is its file, and it must be on disk
+ * (or on Val Remote, read over HTTP) and a kind Val can read the size and
+ * length of here — the same preconditions as `video:add-metadata`, asked of
+ * the key instead of `path`.
+ */
+async function handleVideosetMetadata(ctx) {
+  const key = entryKeyOf(ctx.sourcePath);
+  if (key === undefined) {
+    return {
+      success: false,
+      errorMessage: `Expected a video set entry at ${ctx.sourcePath}`
+    };
+  }
+  const absolute = path__default.join(ctx.projectRoot, key);
+  if (!galleryEntryOf(key).remote && !ctx.fs.fileExists(absolute)) {
     return {
-      localPath: key,
-      remote: true
+      success: false,
+      errorMessage: `File ${absolute} does not exist`
+    };
+  }
+  const entry = ctx.validationError.value;
+  const missing = ["width", "height", "duration"].filter(field => !isRecord$1(entry) || entry[field] === undefined);
+  if (missing.length > 0 && !canReadVideoMetadata(key)) {
+    return {
+      success: false,
+      errorMessage: unreadableVideoMetadataMessage(key, missing)
     };
   }
   return {
-    localPath: key,
-    remote: false
+    success: true,
+    shouldApplyPatch: true
   };
 }
 
 /**
- * The media path a validation error is about, if it is about media at all.
- *
- * There is no schema in hand here — a `ValidationError` carries only the value
- * it flagged — so the shape is all there is to go on.
+ * `videos:check-remote`: a key that is wrong as a key — a remote URL in a set
+ * that is not `.remote()`, one that does not parse, one outside the set's
+ * directory. There is nothing to look up and nothing to move, so the error is
+ * reported as it is, for a person: only they know which of the set's options
+ * or the key is the mistake.
  */
-function getValidationErrorFileRef(validationError) {
-  const maybePath = validationError.value && typeof validationError.value === "object" && "path" in validationError.value && typeof validationError.value.path === "string" ? validationError.value.path : undefined;
-  if (!maybePath) {
-    return null;
-  }
-  return maybePath;
+async function handleVideosetCheckRemote(ctx) {
+  return {
+    success: false,
+    errorMessage: ctx.validationError.message
+  };
 }
 
-const textEncoder$1 = new TextEncoder();
-async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
-  const remoteRefDataRes = Internal.remote.splitRemoteRef(ref);
-  if (remoteRefDataRes.status === "error") {
-    return remoteRefDataRes;
+/**
+ * `videos:upload-remote`: an entry of a `.remote()` set still keyed by a local
+ * path. Every file it holds goes up — a stream bottom-up, as the Studio places
+ * one — and `createFixPatch` renames the key to the ref, the same way
+ * `images:upload-remote` does. The fields that name the entry by its old key
+ * are rewritten too: without that they name a video the set no longer has.
+ *
+ * The entry's poster and captions — its defaults' files — go up with it, and
+ * are what is left to do for an entry whose key is already remote: the key
+ * stays, and the entry is written back with their refs.
+ */
+async function handleVideosetUploadRemote(ctx) {
+  if (!ctx.fix) {
+    return {
+      success: false,
+      // No sourcePath in the message: the reported location already points at it.
+      errorMessage: `Video needs to be uploaded to Val Remote (use --fix to upload)`
+    };
   }
-  const fileHash = remoteRefDataRes.fileHash;
-  if (!fileHash) {
+  const key = ctx.validationError.value;
+  if (typeof key !== "string") {
     return {
-      status: "error",
-      error: `File hash is missing in remote ref: ${ref}`
+      success: false,
+      errorMessage: `Expected a local file path for the video set entry at ${ctx.sourcePath}`
     };
   }
-  const relativeFilePath = remoteRefDataRes.filePath;
-  if (!relativeFilePath) {
+  if (ctx.remoteFiles[ctx.sourcePath]) {
     return {
-      status: "error",
-      error: `File path is missing in remote ref: ${ref}`
+      success: true,
+      shouldApplyPatch: true,
+      events: [{
+        type: "remote-already-uploaded",
+        filePath: key
+      }]
     };
   }
-  if (!relativeFilePath.startsWith("public/")) {
+  const set = resolveVideoset(ctx.valModule, Internal.parentOfSourcePath(ctx.sourcePath));
+  if (!set.success) {
+    return set;
+  }
+  const entry = set.entries[key];
+  if (!isRecord$1(entry)) {
     return {
-      status: "error",
-      error: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
+      success: false,
+      errorMessage: `The video set has no entry '${key}' at ${ctx.sourcePath}`
     };
   }
-  const coreVersion = Internal.VERSION.core || "unknown";
-  const fileExt = getFileExt(relativeFilePath);
-  const currentValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata,
-  // TODO: validate
-  fileHash, textEncoder$1);
-  const validationHashFromRemoteRefValues = Internal.remote.getValidationHash(remoteRefDataRes.version, schema, getFileExt(remoteRefDataRes.filePath), metadata,
-  // TODO: validate
-  fileHash, textEncoder$1);
-  if (
-  // Current validation hash is the same as the remote validation hash
-  // We assume the uploaded file exists and is correct
-  currentValidationHash === remoteRefDataRes.validationHash &&
-  // This can happen if the version or fileExt has been tampered with
-  // (or if the way it is computed has changed)
-  validationHashFromRemoteRefValues === remoteRefDataRes.validationHash) {
+  // The key is local (the entry goes up whole), or the key is already on the
+  // content host and only the entry's poster or captions are still here.
+  const keyIsLocal = !Internal.isRemoteMediaPath(key);
+  const entryFiles = localFilesOfEntry(entry);
+  const missing = firstMissingVideoFile(ctx, [...(keyIsLocal ? [{
+    path: key,
+    ...(typeof entry.mimeType === "string" ? {
+      mimeType: entry.mimeType
+    } : {})
+  }] : []), ...entryFiles.map(file => ({
+    path: file.path
+  }))]);
+  if (missing !== undefined) {
     return {
-      status: "success"
+      success: false,
+      errorMessage: `File ${missing} does not exist`
     };
   }
-  // Validation hash does not match, so we need to re-validate the remote content
-  const fileBufferRes = await getFileBufferFromRemote(ref, fileExt, remoteRefDataRes.fileHash, projectRoot);
-
-  // We could not download the remote file for some reason (for example, the file hash is wrong)
-  if (fileBufferRes.status === "error") {
-    return fileBufferRes;
+  const opened = await openRemoteUploadSession(ctx);
+  if (!opened.success) {
+    return opened.result;
   }
-
-  // At this point we have the file buffer and we know the correct file hash
-  // We must create a new ref since something has changed
-
-  let currentMetadata;
+  const {
+    session
+  } = opened;
+  const uploader = createVideoUploader(ctx, session, videosetEntryVideoSchema(set.record), (localRef, role) => metadataOf(localRef, role, entry));
+  let ref;
   try {
-    if (schema.type === "image") {
-      currentMetadata = await extractImageMetadata(remoteRefDataRes.filePath, fileBufferRes.fileBuffer);
-    } else if (schema.type === "file") {
-      currentMetadata = await extractFileMetadata(remoteRefDataRes.filePath, fileBufferRes.fileBuffer);
-    } else {
-      const exhaustiveCheck = schema;
-      return {
-        status: "error",
-        error: `Unknown schema type: ${JSON.stringify(exhaustiveCheck)}`
-      };
+    ref = keyIsLocal ? await uploader.put(key, "video") : key;
+    for (const file of entryFiles) {
+      await uploader.put(file.path, file.role);
     }
   } catch (err) {
     return {
-      status: "error",
-      error: `Failed to extract metadata from remote file: ${err instanceof Error ? err.message : "Unknown error"}. Cached file: ${fileBufferRes.cachedFilePath}`
+      success: false,
+      errorMessage: err instanceof Error ? err.message : String(err)
     };
   }
-  const updatedMetadata = {
-    ...metadata,
-    ...currentMetadata
+  ctx.remoteFiles[ctx.sourcePath] = {
+    ref,
+    metadata: withMovedFiles(entry, uploader.moved),
+    refs: Object.fromEntries(uploader.moved)
   };
-  const nextValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder$1);
-  if (!updatedMetadata.mimeType) {
+  const otherModulePatches = ref === key ? [] : await videosetReferencePatches(ctx.service, ctx.moduleFilePath, {
+    [key]: ref
+  });
+  return {
+    success: true,
+    shouldApplyPatch: true,
+    publicProjectId: session.publicProjectId,
+    remoteFileBuckets: session.remoteFileBuckets,
+    remoteFilesCounter: session.remoteFilesCounter,
+    events: uploader.events,
+    ...(otherModulePatches.length > 0 ? {
+      otherModulePatches
+    } : {})
+  };
+}
+
+/**
+ * `videos:check-all-files`: the set's entries against its directory.
+ *
+ * What only this handler can answer is which untracked files are accounted
+ * for ELSEWHERE — a poster or caption a video field names — because that needs
+ * every module in the project. Those are fine. An untracked file that is not
+ * a video and that no field names is for a person to look at, and is reported
+ * here. Everything `--fix` can do something about — an entry whose file has
+ * gone, a video in the directory the set does not list — is left to
+ * `createFixPatch` (see {@link videosetCheckAllFilesPatch}), which reports it
+ * per entry, or repairs it.
+ */
+async function handleVideosetCheckAllFiles(ctx) {
+  const value = ctx.validationError.value;
+  const dir = isRecord$1(value) ? value.dir : undefined;
+  if (typeof dir !== "string") {
     return {
-      status: "error",
-      error: `MIME type is missing in metadata: ${JSON.stringify(updatedMetadata)}`
+      success: false,
+      errorMessage: `Unexpected value in check-all-files for ${ctx.sourcePath}`
     };
   }
-  const newFileExt = Internal.mimeTypeToFileExt(updatedMetadata.mimeType);
-  const newFilePath = relativeFilePath.slice(0, -fileExt.length) + newFileExt;
-  return {
-    status: "fix-required",
-    metadata: updatedMetadata,
-    ref: Internal.remote.createRemoteRef(remoteHost, {
-      publicProjectId: remoteRefDataRes.projectId,
-      coreVersion,
-      bucket: remoteRefDataRes.bucket,
-      validationHash: nextValidationHash,
-      fileHash: fileBufferRes.fileHash,
-      filePath: newFilePath
+  const set = resolveVideoset(ctx.valModule, ctx.sourcePath);
+  if (!set.success) {
+    return set;
+  }
+  const readFile = absolute => ctx.fs.readBuffer(absolute);
+  const incompleteEntries = incompleteGalleryEntries({
+    entryKeys: Object.keys(set.entries),
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs,
+    filesOfEntry: (entry, key) => filesOfVideosetEntry(entry, set.entries[key], {
+      projectRoot: ctx.projectRoot,
+      readFile
+    })
+  });
+  const {
+    untrackedFiles
+  } = checkGalleryFiles({
+    entryKeys: Object.keys(set.entries),
+    dir,
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs,
+    filesOfEntry: (entry, key) => filesOfVideosetEntry(entry, set.entries[key], {
+      projectRoot: ctx.projectRoot,
+      readFile
     })
+  });
+  if (incompleteEntries.length > 0) {
+    return {
+      success: false,
+      errorMessage: incompleteMessage(incompleteEntries)
+    };
+  }
+  if (untrackedFiles.length === 0) {
+    return {
+      success: true,
+      shouldApplyPatch: true
+    };
+  }
+  const named = await filesNamedByVideoFields(ctx.service, {
+    projectRoot: ctx.projectRoot,
+    readFile
+  });
+  const {
+    others
+  } = classifyUntrackedVideosetFiles({
+    untracked: untrackedFiles.filter(file => !named.has(file)),
+    accept: set.record.accept ?? "video/*",
+    projectRoot: ctx.projectRoot,
+    readFile
+  });
+  if (others.length > 0) {
+    return {
+      success: false,
+      errorMessage: `Video set in ${ctx.moduleFilePath} has files in '${dir}' that are not in the set, and that no video field uses: ${others.join(", ")}. They are not videos the set accepts, so --fix will not add them: move them out of the directory or remove them.`
+    };
+  }
+  return {
+    success: true,
+    shouldApplyPatch: true
   };
 }
-function getCachedRemoteFileDir(projectRoot) {
-  // store in projectRoot/.val/remote-file-cache
-  const remoteFileCacheDir = path__default.join(projectRoot, ".val", "remote-file-cache");
-  return remoteFileCacheDir;
-}
-function getCachedRemoteFilePath(fileExt, currentFileHash, remoteFileCacheDir) {
-  const remoteFilePath = path__default.join(remoteFileCacheDir, currentFileHash + "." + fileExt);
-  return remoteFilePath;
-}
-async function getFileBufferFromRemote(ref, fileExt, currentFileHash, projectRoot) {
-  const remoteFileCacheDir = getCachedRemoteFileDir(projectRoot);
-  const remoteFilePath = getCachedRemoteFilePath(fileExt, currentFileHash, remoteFileCacheDir);
-  try {
-    const fileBuffer = await fs.promises.readFile(remoteFilePath);
-    const computedFileHash = Internal.remote.getFileHash(fileBuffer);
-    if (computedFileHash !== currentFileHash) {
-      await fs.promises.unlink(remoteFilePath);
-      throw Error(`Cached file hash does not match the expected hash: ${computedFileHash} !== ${currentFileHash}`);
+
+/**
+ * The `createFixPatch` half of `videos:check-all-files`: drop the entries
+ * whose file has gone, and add the videos in the directory that the set does
+ * not list — with what is read from their bytes, or not at all.
+ *
+ * What is stored for an entry that IS on disk is not compared against its
+ * bytes, unlike an image gallery's. The Studio reads a video's size and length
+ * in the browser from the file as it was picked, and that is not what a header
+ * parse of what is on disk says: a stream's largest rendition is not the
+ * upload's size whenever the upload was larger than the largest rendition, and
+ * two readers round a duration differently. Correcting one from the other
+ * would rewrite every streamed video in the project, every run. A missing
+ * value is `videos:add-metadata`'s, and is reported on the entry.
+ */
+async function videosetCheckAllFilesPatch({
+  projectRoot,
+  apply,
+  sourcePath,
+  validationError,
+  moduleSource,
+  moduleSchema
+}) {
+  const patch = [];
+  const remainingErrors = [];
+  const fail = message => ({
+    patch,
+    remainingErrors: [{
+      ...validationError,
+      message,
+      fixes: undefined
+    }]
+  });
+  const value = validationError.value;
+  const dir = isRecord$1(value) ? value.dir : undefined;
+  if (typeof dir !== "string") {
+    return fail(`Unexpected value in check-all-files for ${sourcePath}`);
+  }
+  if (moduleSource === undefined || moduleSchema === undefined) {
+    return fail("Unexpected error while checking a video set (no module source or schema)");
+  }
+  const set = resolveVideoset({
+    source: moduleSource,
+    schema: moduleSchema
+  }, sourcePath);
+  if (!set.success) {
+    return fail(set.errorMessage);
+  }
+  const recordPath = patchPathOf(sourcePath);
+  const incompleteEntries = incompleteGalleryEntries({
+    entryKeys: Object.keys(set.entries),
+    projectRoot,
+    fs: ts.sys,
+    filesOfEntry: (entry, key) => filesOfVideosetEntry(entry, set.entries[key], {
+      projectRoot
+    })
+  });
+  const {
+    missingTrackedFiles,
+    untrackedFiles
+  } = checkGalleryFiles({
+    entryKeys: Object.keys(set.entries),
+    dir,
+    projectRoot,
+    // The host `createDefaultValFSHost` gives the handlers, and so the same
+    // listing the handler half of this check saw.
+    fs: ts.sys,
+    filesOfEntry: (entry, key) => filesOfVideosetEntry(entry, set.entries[key], {
+      projectRoot
+    })
+  });
+  if (incompleteEntries.length > 0) {
+    remainingErrors.push({
+      ...validationError,
+      message: incompleteMessage(incompleteEntries),
+      fixes: undefined
+    });
+  }
+  for (const missing of missingTrackedFiles) {
+    if (apply) {
+      const removePath = recordPath.concat(missing);
+      if (isNotRoot(removePath)) {
+        patch.push({
+          op: "remove",
+          path: removePath
+        });
+      }
+    } else {
+      remainingErrors.push({
+        ...validationError,
+        message: `Video '${missing}' is in the set, but its file does not exist. Use --fix to remove it from the set.`,
+        sourcePath: Internal.createValPathOfItem(sourcePath, missing),
+        keyError: true
+      });
     }
-  } catch {
+  }
+  const {
+    videos
+  } = classifyUntrackedVideosetFiles({
+    untracked: untrackedFiles,
+    accept: set.record.accept ?? "video/*",
+    projectRoot
+  });
+  for (const file of videos) {
+    let metadata;
     try {
-      await fs.promises.mkdir(remoteFileCacheDir, {
-        recursive: true
+      metadata = await extractVideoMetadataFromFile(path__default.join(projectRoot, file));
+    } catch (err) {
+      remainingErrors.push({
+        ...validationError,
+        message: `Video '${file}' is in '${dir}' but not in the set, and its metadata could not be read: ${err instanceof Error ? err.message : String(err)}`,
+        fixes: undefined
+      });
+      continue;
+    }
+    const unreadable = VIDEO_METADATA_FIELDS$1.filter(field => metadata[field] === undefined);
+    if (unreadable.length > 0) {
+      // All or nothing, as for `video:add-metadata`: an entry with a mime type
+      // and no size is no closer to valid, and reads as one someone finished.
+      remainingErrors.push({
+        ...validationError,
+        message: `Video '${file}' is in '${dir}' but not in the set. ${unreadableVideoMetadataMessage(file, unreadable)}`,
+        fixes: undefined
+      });
+      continue;
+    }
+    if (!apply) {
+      remainingErrors.push({
+        ...validationError,
+        message: `Video '${file}' is in '${dir}' but not in the set. Use --fix to add it.`
+      });
+      continue;
+    }
+    const entry = {};
+    for (const field of VIDEO_METADATA_FIELDS$1) {
+      const read = metadata[field];
+      if (read !== undefined) {
+        entry[field] = read;
+      }
+    }
+    // What an upload writes when nobody has described the video yet.
+    entry.alt = null;
+    const addPath = recordPath.concat(file);
+    if (isNotRoot(addPath)) {
+      patch.push({
+        op: "add",
+        path: addPath,
+        value: entry
+      });
+    }
+  }
+  return {
+    patch,
+    remainingErrors
+  };
+}
+
+/**
+ * The `createFixPatch` half of `videos:add-metadata`: read what is missing
+ * from the file at the entry's KEY, and write only that, one op per field —
+ * `alt` and anything already there are someone's, and stay.
+ */
+async function videosetAddMetadataPatch({
+  projectRoot,
+  sourcePath,
+  validationError,
+  moduleSource,
+  moduleSchema
+}) {
+  const fail = message => ({
+    patch: [],
+    remainingErrors: [{
+      ...validationError,
+      message,
+      fixes: undefined
+    }]
+  });
+  const key = entryKeyOf(sourcePath);
+  if (key === undefined) {
+    return fail(`Expected a video set entry at ${sourcePath}`);
+  }
+  let current = validationError.value;
+  if (moduleSource !== undefined && moduleSchema !== undefined) {
+    const parent = resolveVideoset({
+      source: moduleSource,
+      schema: moduleSchema
+    }, Internal.parentOfSourcePath(sourcePath));
+    if (!parent.success) {
+      return fail(`Could not add video metadata: ${parent.errorMessage}`);
+    }
+    current = parent.entries[key];
+  }
+  if (!isRecord$1(current)) {
+    return fail("Video set entry is not an object!");
+  }
+  let metadata;
+  try {
+    metadata = galleryEntryOf(key).remote ? await extractVideoMetadataFromUrl(key, nameForTypeOf(key)) : await extractVideoMetadataFromFile(path__default.join(projectRoot, key));
+  } catch (err) {
+    return fail(`Failed to read video metadata from ${key}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const entry = current;
+  const missing = VIDEO_METADATA_FIELDS$1.filter(field => entry[field] === undefined);
+  const unreadable = missing.filter(field => metadata[field] === undefined);
+  if (unreadable.length > 0) {
+    return fail(unreadableVideoMetadataMessage(key, unreadable));
+  }
+  const entryPath = patchPathOf(sourcePath);
+  const patch = [];
+  for (const field of missing) {
+    const read = metadata[field];
+    if (read !== undefined) {
+      patch.push({
+        op: "add",
+        path: entryPath.concat(field),
+        value: read
       });
-      await downloadFileFromRemote(ref, remoteFilePath);
-    } catch (err) {
-      try {
-        // try to delete in case of partial download
-        await fs.promises.unlink(remoteFilePath);
-      } catch {
-        //
-      }
-      return {
-        status: "error",
-        error: `Failed to download remote file: ${err instanceof Error ? err.message : "Unknown error"}`
-      };
     }
   }
-  const fileBuffer = await fs.promises.readFile(remoteFilePath);
-  const computedFileHash = Internal.remote.getFileHash(fileBuffer);
   return {
-    status: "success",
-    fileBuffer,
-    fileHash: computedFileHash,
-    cachedFilePath: remoteFilePath
+    patch,
+    remainingErrors: []
   };
 }
-async function downloadFileFromRemote(ref, filePath) {
-  return new Promise((resolve, reject) => {
-    const url = new URL(ref);
-    const client = url.protocol === "https:" ? https$1 : http$1;
-    const request = client.get(url, response => {
-      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-        // Handle redirects
-        return downloadFileFromRemote(response.headers.location, filePath).then(resolve).catch(reject);
-      }
-      if (response.statusCode == 404) {
-        return reject(new Error(`${ref}. File not found. The URL is most likely incorrect.`));
-      }
-      if (response.statusCode !== 200) {
-        return reject(new Error(`${ref}. Failed to download file. HTTP Status: ${response.statusCode}`));
-      }
-      const writeStream = fs.createWriteStream(filePath);
-      response.pipe(writeStream);
-      writeStream.on("finish", () => resolve({
-        status: "success",
-        filePath
-      }));
-      writeStream.on("error", err => reject(new Error(`${ref}. Error writing file: ${err.message}`)));
-    });
-    request.on("error", err => reject(new Error(`${ref}. Download error: ${err.message}`)));
-    request.end();
-  });
+
+/**
+ * What to say about streams whose master is there and some of whose files are
+ * not. Not fixable: the entry still names a video someone uploaded, and only
+ * they have the rest of it.
+ */
+function incompleteMessage(incomplete) {
+  return incomplete.map(({
+    key,
+    missing
+  }) => `Video '${key}' is missing ${missing.length === 1 ? "a file it names" : `${missing.length} files it names`}: ${missing.join(", ")}. It stops playing where they are. Upload it again, or put the files back.`).join(" ");
 }
 
 // A remaining error may optionally carry a more specific `sourcePath` than the
@@ -18283,6 +21120,86 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
           value: fileMetadata.mimeType ?? null
         });
       }
+    } else if (fix === "video:add-metadata") {
+      // Only the fields that are MISSING, one op each: a video's `alt`,
+      // `poster`, `captions` and times are authored and sit in the same
+      // object, and a field already there is not re-read (see the comment on
+      // the fix code in core — reading a video is not cheap).
+      const current = currentVideoValue(sourcePath, validationError, moduleSource, moduleSchema);
+      if (current.status === "error") {
+        remainingErrors.push({
+          ...validationError,
+          message: current.message,
+          fixes: undefined
+        });
+        continue;
+      }
+      const fileRef = current.value.path;
+      if (typeof fileRef !== "string") {
+        remainingErrors.push({
+          ...validationError,
+          message: `Cannot read video metadata: the video has no path`,
+          fixes: undefined
+        });
+        continue;
+      }
+      let metadata;
+      try {
+        metadata = await getVideoMetadata(config.projectRoot, fileRef);
+      } catch (err) {
+        remainingErrors.push({
+          ...validationError,
+          message: `Failed to read video metadata from ${fileRef}: ${err instanceof Error ? err.message : String(err)}`,
+          fixes: undefined
+        });
+        continue;
+      }
+      const missing = VIDEO_METADATA_FIELDS.filter(field => current.value[field] === undefined);
+      const unreadable = missing.filter(field => metadata[field] === undefined);
+      if (unreadable.length > 0) {
+        // All or nothing: a video with a mime type but no size is no closer
+        // to valid, and a half-written value reads as one someone finished.
+        remainingErrors.push({
+          ...validationError,
+          message: unreadableVideoMetadataMessage(fileRef, unreadable),
+          fixes: undefined
+        });
+        continue;
+      }
+      const patchPath = sourceToPatchPath(sourcePath);
+      for (const field of missing) {
+        const value = metadata[field];
+        if (value !== undefined) {
+          patch.push({
+            op: "add",
+            path: patchPath.concat(field),
+            value
+          });
+        }
+      }
+    } else if (fix === "videos:add-metadata") {
+      // A set entry's twin of `video:add-metadata`: the file is the entry's
+      // KEY, and only what is missing is written.
+      const fixed = await videosetAddMetadataPatch({
+        projectRoot: config.projectRoot,
+        sourcePath,
+        validationError,
+        moduleSource,
+        moduleSchema
+      });
+      patch.push(...fixed.patch);
+      remainingErrors.push(...fixed.remainingErrors);
+    } else if (fix === "videos:check-all-files") {
+      const fixed = await videosetCheckAllFilesPatch({
+        projectRoot: config.projectRoot,
+        apply,
+        sourcePath,
+        validationError,
+        moduleSource,
+        moduleSchema
+      });
+      patch.push(...fixed.patch);
+      remainingErrors.push(...fixed.remainingErrors);
     } else if (fix === "image:upload-remote" || fix === "file:upload-remote") {
       const remoteFile = remoteFiles[sourcePath];
       let metadata = remoteFile.metadata;
@@ -18312,10 +21229,30 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
           path: sourceToPatchPath(sourcePath)
         });
       }
-    } else if (fix === "images:upload-remote" || fix === "files:upload-remote") {
+    } else if (fix === "video:upload-remote" || fix === "video:download-remote") {
+      var _remoteFiles$sourcePa;
+      // The handler moved the files (`videoRemote.ts`); what is left is to
+      // point each path the value holds at where its file now is. Read from
+      // the module rather than the error, which carries the value as it was
+      // validated.
+      const moved = (_remoteFiles$sourcePa = remoteFiles[sourcePath]) === null || _remoteFiles$sourcePa === void 0 ? void 0 : _remoteFiles$sourcePa.refs;
+      if (!moved) {
+        remainingErrors.push({
+          ...validationError,
+          message: fix === "video:upload-remote" ? "Cannot point the video at Val Remote: its files were not uploaded" : "Cannot point the video at its local files: they were not downloaded",
+          fixes: undefined
+        });
+        continue;
+      }
+      const current = moduleSource !== undefined && moduleSchema !== undefined ? Internal.resolvePath(Internal.splitModuleFilePathAndModulePath(sourcePath)[1], moduleSource, moduleSchema).source : validationError.value;
+      patch.push(...rewriteVideoPathsPatch(sourcePath, current, moved));
+    } else if (fix === "images:upload-remote" || fix === "files:upload-remote" || fix === "videos:upload-remote") {
       // Gallery entry: the record is keyed by the file path, so uploading to
       // remote means renaming the key from the local path to the remote URL
-      // (remove the old key, add the new one with the same metadata).
+      // (remove the old key, add the new one with the same metadata). A video
+      // set's entry is renamed to its MASTER playlist's ref for a stream: the
+      // playlists and segments it names went up with it, and are named by the
+      // uploaded master, not by the set.
       const remoteFile = remoteFiles[sourcePath];
       if (!remoteFile) {
         remainingErrors.push({
@@ -18674,6 +21611,52 @@ function getRemoteValueFromValidationError(v) {
     metadata
   };
 }
+
+/** The fields of a video that are read from its bytes, in the order written. */
+const VIDEO_METADATA_FIELDS = ["mimeType", "width", "height", "duration"];
+
+/**
+ * The video a `video:add-metadata` error is about, read from the module at its
+ * path when the module is at hand — the schema there decides that it IS a
+ * video — and from the error's own value otherwise.
+ */
+function currentVideoValue(sourcePath, validationError, moduleSource, moduleSchema) {
+  if (moduleSource !== undefined && moduleSchema !== undefined) {
+    const [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+    const resolved = Internal.resolvePath(modulePath, moduleSource, moduleSchema);
+    if (resolved.schema.type !== "video") {
+      return {
+        status: "error",
+        message: `Could not add video metadata: schema at ${sourcePath} is '${resolved.schema.type}', not a video`
+      };
+    }
+    const value = mediaValueOf(resolved.source);
+    return value ? {
+      status: "ok",
+      value
+    } : {
+      status: "error",
+      message: "Video is not an object!"
+    };
+  }
+  const value = mediaValueOf(validationError.value);
+  return value ? {
+    status: "ok",
+    value
+  } : {
+    status: "error",
+    message: "Video is not an object!"
+  };
+}
+async function getVideoMetadata(projectRoot, fileRef) {
+  // Not read into memory: only the headers are, and a video is mostly not
+  // headers. A remote video's headers are read over HTTP, with Range
+  // requests, so it is not downloaded either.
+  if (Internal.isRemoteMediaPath(fileRef)) {
+    return extractVideoMetadataFromUrl(fileRef, nameForTypeOf(fileRef));
+  }
+  return extractVideoMetadataFromFile(path__default.join(projectRoot, fileRef));
+}
 async function getImageMetadata(projectRoot, validationError) {
   const fileRef = getValidationErrorFileRef(validationError);
   if (!fileRef) {
@@ -18847,10 +21830,17 @@ function formatOpsError(error, sourceFile) {
  * What stays in the CLI is the driver: the `runValidation` async generator that
  * walks every module, decides what to report, and renders it to a terminal.
  */
-const textEncoder = new TextEncoder();
 
 // Types for handler system
 
+/**
+ * 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.
+ */
+
+/** A patch, and the module it is for. */
+
 // Handler functions
 async function handleFileMetadata(ctx) {
   var _fileSource$source;
@@ -18884,6 +21874,53 @@ async function handleFileMetadata(ctx) {
   };
 }
 
+/**
+ * `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.
+ */
+async function handleVideoMetadata(ctx) {
+  const exists = isRemoteVideoAt(ctx) ? {
+    success: true,
+    shouldApplyPatch: true
+  } : await handleFileMetadata(ctx);
+  if (!exists.success) {
+    return exists;
+  }
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
+    return exists;
+  }
+  const video = Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema).source;
+  if (!isRecord(video) || typeof video.path !== "string") {
+    return exists;
+  }
+  const missing = ["width", "height", "duration"].filter(field => video[field] === undefined);
+  if (missing.length > 0 && !canReadVideoMetadata(video.path)) {
+    return {
+      success: false,
+      errorMessage: unreadableVideoMetadataMessage(video.path, missing)
+    };
+  }
+  return exists;
+}
+
+/** Whether the video at the error's path is on Val Remote. */
+function isRemoteVideoAt(ctx) {
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
+    return false;
+  }
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  const video = Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema).source;
+  return isRecord(video) && typeof video.path === "string" && Internal.isRemoteMediaPath(video.path);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // Shared upload core used by both the single-field (handleRemoteFileUpload)
 // and gallery (handleRemoteGalleryFileUpload) handlers. The two differ only in
 // how they derive the local file ref, metadata and serialized image/file
@@ -18896,30 +21933,6 @@ async function uploadRemoteFileCore(ctx, fileRef, metadata, schema) {
       errorMessage: `File ${filePath} does not exist`
     };
   }
-  const patFile = getPersonalAccessTokenPath(ctx.projectRoot);
-  if (!ctx.fs.fileExists(patFile)) {
-    return {
-      success: false,
-      errorMessage: `File: ${path__default.join(ctx.projectRoot, ctx.file)} has remote images that are not uploaded and you are not logged in.\n\nFix this error by logging in:\n\t"npx val login"\n`
-    };
-  }
-  const patFileContent = ctx.fs.readFile(patFile);
-  if (patFileContent === undefined) {
-    return {
-      success: false,
-      errorMessage: `Could not read personal access token file at ${patFile}`
-    };
-  }
-  const parsedPatFile = parsePersonalAccessTokenFile(patFileContent);
-  if (!parsedPatFile.success) {
-    return {
-      success: false,
-      errorMessage: `Error parsing personal access token file: ${parsedPatFile.error}. You need to login again.`
-    };
-  }
-  const {
-    pat
-  } = parsedPatFile.data;
   if (ctx.remoteFiles[ctx.sourcePath]) {
     return {
       success: true,
@@ -18929,49 +21942,13 @@ async function uploadRemoteFileCore(ctx, fileRef, metadata, schema) {
       }]
     };
   }
-  const projectName = ctx.project;
-  let publicProjectId = ctx.publicProjectId;
-  let remoteFileBuckets = ctx.remoteFileBuckets;
-  let remoteFilesCounter = ctx.remoteFilesCounter;
-  if (!publicProjectId || !remoteFileBuckets) {
-    if (!projectName) {
-      return {
-        success: false,
-        errorMessage: "Project name not found. Add project name to val.config or set the VAL_PROJECT environment variable"
-      };
-    }
-    const settingsRes = await ctx.remote.getSettings(projectName, {
-      pat
-    });
-    if (!settingsRes.success) {
-      return {
-        success: false,
-        errorMessage: `Could not get public project id: ${settingsRes.message}.`
-      };
-    }
-    publicProjectId = settingsRes.data.publicProjectId;
-    remoteFileBuckets = settingsRes.data.remoteFileBuckets.map(b => b.bucket);
-  }
-  if (!publicProjectId) {
-    return {
-      success: false,
-      errorMessage: "Could not get public project id"
-    };
-  }
-  if (!projectName) {
-    return {
-      success: false,
-      errorMessage: `Could not get project. Check that your val.config has the 'project' field set, or set it using the VAL_PROJECT environment variable`
-    };
-  }
-  remoteFilesCounter += 1;
-  const bucket = remoteFileBuckets[remoteFilesCounter % remoteFileBuckets.length];
-  if (!bucket) {
-    return {
-      success: false,
-      errorMessage: `Internal error: could not allocate a bucket for the remote file located at ${ctx.sourcePath}`
-    };
+  const opened = await openRemoteUploadSession(ctx);
+  if (!opened.success) {
+    return opened.result;
   }
+  const {
+    session
+  } = opened;
   const fileBuffer = ctx.fs.readBuffer(filePath);
   if (fileBuffer === undefined) {
     return {
@@ -18980,32 +21957,16 @@ async function uploadRemoteFileCore(ctx, fileRef, metadata, schema) {
     };
   }
   const relativeFilePath = path__default.relative(ctx.projectRoot, filePath).split(path__default.sep).join("/");
-  if (!relativeFilePath.startsWith("public/")) {
-    return {
-      success: false,
-      errorMessage: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
-    };
-  }
-  const fileHash = Internal.remote.getFileHash(fileBuffer);
-  const coreVersion = Internal.VERSION.core || "unknown";
-  const fileExt = getFileExt(filePath);
-  const ref = Internal.remote.createRemoteRef(ctx.remote.remoteHost, {
-    publicProjectId,
-    coreVersion,
-    bucket,
-    validationHash: Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata, fileHash, textEncoder),
-    fileHash,
-    filePath: relativeFilePath
-  });
-  const remoteFileUpload = await ctx.remote.uploadFile(projectName, bucket, fileHash, fileExt, fileBuffer, {
-    pat
-  });
-  if (!remoteFileUpload.success) {
+  const uploaded = await uploadBytesToRemote(ctx, session, relativeFilePath, fileBuffer, metadata, schema);
+  if (!uploaded.success) {
     return {
       success: false,
-      errorMessage: `Could not upload remote file: '${ref}'. Error: ${remoteFileUpload.error}`
+      errorMessage: uploaded.error
     };
   }
+  const {
+    ref
+  } = uploaded;
   ctx.remoteFiles[ctx.sourcePath] = {
     ref,
     metadata
@@ -19013,9 +21974,9 @@ async function uploadRemoteFileCore(ctx, fileRef, metadata, schema) {
   return {
     success: true,
     shouldApplyPatch: true,
-    publicProjectId,
-    remoteFileBuckets,
-    remoteFilesCounter,
+    publicProjectId: session.publicProjectId,
+    remoteFileBuckets: session.remoteFileBuckets,
+    remoteFilesCounter: session.remoteFilesCounter,
     events: [{
       type: "remote-uploading",
       ref
@@ -19216,50 +22177,6 @@ async function handleUniqueFolderCheck(ctx) {
     success: true
   };
 }
-
-/**
- * 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.
- */
-function checkGalleryFiles(input) {
-  const {
-    dir,
-    projectRoot,
-    fs
-  } = input;
-  const entries = input.entryKeys.map(galleryEntryOf);
-  const trackedFiles = new Set(entries.map(entry => entry.localPath));
-  const missingTrackedFiles = entries.filter(entry => !entry.remote && !fs.fileExists(path__default.join(projectRoot, entry.localPath))).map(entry => entry.localPath);
-  const filesInDir = [];
-  try {
-    const found = fs.readDirectory(path__default.join(projectRoot, dir), undefined, undefined, ["**/*"]);
-    for (const entry of found) {
-      filesInDir.push("/" + path__default.relative(projectRoot, entry).split(path__default.sep).join("/"));
-    }
-  } catch {
-    // directory doesn't exist — no untracked files possible
-  }
-  return {
-    missingTrackedFiles,
-    untrackedFiles: filesInDir.filter(f => !trackedFiles.has(f))
-  };
-}
 async function handleCheckAllFiles(ctx) {
   const value = ctx.validationError.value;
   if (!value || typeof value.dir !== "string") {
@@ -19406,12 +22323,20 @@ const currentFixHandlers = {
   "image:add-metadata": handleFileMetadata,
   "file:check-metadata": handleFileMetadata,
   "file:add-metadata": handleFileMetadata,
+  "video:add-metadata": handleVideoMetadata,
   "image:upload-remote": handleRemoteFileUpload,
   "file:upload-remote": handleRemoteFileUpload,
   "images:upload-remote": handleRemoteGalleryFileUpload,
   "files:upload-remote": handleRemoteGalleryFileUpload,
   "image:download-remote": handleRemoteFileDownload,
   "file:download-remote": handleRemoteFileDownload,
+  "video:upload-remote": handleVideoUploadRemote,
+  "video:download-remote": handleVideoDownloadRemote,
+  "videos:add-metadata": handleVideosetMetadata,
+  "videos:upload-remote": handleVideosetUploadRemote,
+  "videos:check-remote": handleVideosetCheckRemote,
+  "videos:check-unique-folder": handleUniqueFolderCheck,
+  "videos:check-all-files": handleVideosetCheckAllFiles,
   "image:check-remote": handleRemoteFileCheck,
   "images:check-remote": handleRemoteFileCheck,
   "file:check-remote": handleRemoteFileCheck,
@@ -19607,20 +22532,15 @@ function createPrettierFormatter(prettier, options) {
 }
 
 /**
- * NOTE: this is intentionally NOT `SharedValConfig` from `@valbuild/shared`.
- * That schema requires `files.directory` to be exactly `/public/val`, whereas
- * this one accepts any path beneath `/public`. Unifying them would change which
- * configs are accepted, so they are kept separate on purpose.
+ * NOTE: this is intentionally NOT `SharedValConfig` from `@valbuild/shared`,
+ * which leaves `files` out: `files.remote` decides how the schemas are built,
+ * so it is read where `val.config.ts` is, not shared with the client.
  */
 const ValConfigSchema = z$1.object({
   project: z$1.string().optional(),
   root: z$1.string().optional(),
   files: z$1.object({
-    directory: z$1.string().refine(val => (val === "/public" || val.startsWith("/public/") && !val.endsWith("/")) &&
-    // Reject path traversal so the directory cannot escape /public
-    !val.split("/").some(segment => segment === "." || segment === ".."), {
-      message: "files.directory must start with '/public', must not end with '/' and must not contain '.' or '..' segments"
-    })
+    remote: z$1.boolean().optional()
   }).optional(),
   gitCommit: z$1.string().optional(),
   gitBranch: z$1.string().optional(),
@@ -20109,7 +23029,7 @@ async function replaySnapshot(snapshotDir) {
   const serverOps = new ValOpsFS(process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST, root, valModules,
   // The snapshot's own val.config, as evaluated by loadValModules - no need to
   // re-read it, and this way the replay uses exactly the config the snapshot
-  // carries (files.directory in particular).
+  // carries.
   {
     config: valModules.config
   });
@@ -20188,4 +23108,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, InMemoryPatchStore, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValOpsMemory, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createPrettierFormatter, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findDefaultExport, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, planJsonValuesEntryExtraction, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { APP_MODE_REQUIRES_REMOTE_FILES, DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, InMemoryPatchStore, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValOpsMemory, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createPrettierFormatter, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, extractVideoMetadata, extractVideoMetadataFromFile, filesOfVideo, filesOfVideosetEntry, findAndEvalValConfigFile, findDefaultExport, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, handleVideosetCheckAllFiles, handleVideosetCheckRemote, handleVideosetMetadata, handleVideosetUploadRemote, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, planJsonValuesEntryExtraction, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt, videosetEntryVideoSchema };