@valbuild/core 0.121.0 → 0.124.0

package/dist/{index-61237991.cjs.prod.js → index-22a40d42.cjs.prod.js}

@@ -1964,7 +1964,7 @@ var union = function union(key) {
   return new UnionSchema(key, objects);
 };
 
-var RegEx = /^(https?:\/\/[^/]+)\/file\/p\/([^/]+)\/b\/([^/]+)\/v\/([^/]+)\/h\/([^/]+)\/f\/([^/]+)\/p\/(.+)$/;
+var RegEx$1 = /^(https?:\/\/[^/]+)\/file\/p\/([^/]+)\/b\/([^/]+)\/v\/([^/]+)\/h\/([^/]+)\/f\/([^/]+)\/p\/(.+)$/;
 function splitRemoteRef(ref) {
   if (ref[0] === "/") {
     return {
@@ -1972,7 +1972,7 @@ function splitRemoteRef(ref) {
       error: "Not a remote ref: " + ref
     };
   }
-  var match = ref.match(RegEx);
+  var match = ref.match(RegEx$1);
   if (!match) {
     return {
       status: "error",
@@ -4370,6 +4370,94 @@ function _resolveJsonValues() {
   return _resolveJsonValues.apply(this, arguments);
 }
 
+/**
+ * The string used as the `_type` discriminator of an {@link ExternalRecordSrc}.
+ */
+var EXTERNAL_VAL_EXTENSION_TAG = "external";
+
+/**
+ * Type-level-only slots. Declared here rather than reusing `PhantomType`
+ * (`source/index.ts`) because three separate facts have to ride along, and that
+ * helper carries one.
+ *
+ * None of them exist at runtime: `c.external()` produces `{ _type: "external" }`
+ * and nothing else.
+ */
+
+/**
+ * The source of a record whose entries live behind an adapter — a database, an
+ * HTTP API, a bucket — instead of in the module.
+ *
+ * This is what `c.external()` returns, and it is the counterpart of the
+ * `c.json(() => import(...))` marker a `.jsonValues()` entry carries: a value
+ * that says "the content is not here" without saying anything about what is.
+ * The schema says *which* adapter (`.external("posts")`); this says *that* the
+ * entries are elsewhere, which is what every source-walking consumer needs to
+ * know without holding a schema.
+ *
+ * Three phantom parameters, each earning its place:
+ *
+ * - `T` — the item type. Without it `c.define` would return a module whose type
+ *   is "a marker", the item type would be gone, and an adapter could not be
+ *   typed from the schema at all.
+ * - `L` — the label from `.external(label)`, so a binding can be checked against
+ *   the schema that declared it.
+ * - `RO` — whether the schema said `.readonly()`, which decides whether the
+ *   adapter must implement writes or is forbidden from doing so.
+ *
+ * The defaults are the WIDEST instantiation on purpose: the bare name appears in
+ * the `Source` and `SelectorSource` unions, and every narrower instantiation has
+ * to be assignable to it. The `external()` factory below defaults the other way,
+ * exactly as `JsonSource<T = unknown>` and `json<T = Json>()` do.
+ */
+
+/**
+ * The marker written as a module's source when its record is `.external()`.
+ *
+ * Takes no arguments: everything it carries is inferred from the schema it is
+ * checked against in `c.define`. The assertion mirrors `json()` — the phantom
+ * slots are symbol-keyed and have no runtime representation, so there is nothing
+ * to construct for them.
+ */
+function external() {
+  return _defineProperty({}, VAL_EXTENSION, EXTERNAL_VAL_EXTENSION_TAG);
+}
+function isExternal(obj) {
+  return _typeof(obj) === "object" && obj !== null && VAL_EXTENSION in obj && obj[VAL_EXTENSION] === EXTERNAL_VAL_EXTENSION_TAG;
+}
+
+/**
+ * The item type an external record holds, read back off a module.
+ *
+ * `GenericSelector` is not imported here — that would be a cycle through
+ * `../selector` — so this is written against the phantom slot directly and the
+ * selector-shaped overloads live where the selector types do.
+ */
+
+/** The label an external record was declared with. */
+
+/** Whether the schema behind an external record said `.readonly()`. */
+
+/**
+ * The source of an external record as it may be WRITTEN.
+ *
+ * Either the marker, or entries inline in the `.val.ts`. Inline entries are
+ * accepted by the type on purpose, for the same reason `.jsonValues()` accepts
+ * them (see `JsonValuesRecordSrc`): pasting content straight into the module is
+ * the natural first thing to write, and a type error there is a dead end — the
+ * author cannot see what to write instead. Validation reports the inline entries
+ * as an `external:upload` fix instead, so the mistake is repaired rather than
+ * blocking authoring, and they are readable at runtime meanwhile.
+ */
+
+/**
+ * Is this module source an external record that still has entries written
+ * inline? Used by validation to raise `external:upload`.
+ */
+function hasInlineExternalEntries(source) {
+  return _typeof(source) === "object" && source !== null && !Array.isArray(source) && !isExternal(source) && Object.keys(source).length > 0;
+}
+
 /**
  * The source type of a `.jsonValues()` record: every entry value is EITHER a
  * lazily loaded {@link JsonSource} whose resolved content is the (loosened, see
@@ -4398,6 +4486,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     var isJsonValues = arguments.length > 9 && arguments[9] !== undefined ? arguments[9] : false;
     var previewInput = arguments.length > 10 && arguments[10] !== undefined ? arguments[10] : null;
     var renderInput = arguments.length > 11 && arguments[11] !== undefined ? arguments[11] : null;
+    var externalLabel = arguments.length > 12 && arguments[12] !== undefined ? arguments[12] : null;
     _classCallCheck(this, RecordSchema);
     _this = _callSuper(this, RecordSchema);
     _this.item = item;
@@ -4412,24 +4501,28 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     _this.isJsonValues = isJsonValues;
     _this.previewInput = previewInput;
     _this.renderInput = renderInput;
+    _this.externalLabel = externalLabel;
     return _this;
   }
   _inherits(RecordSchema, _Schema);
   return _createClass(RecordSchema, [{
     key: "describe",
     value: function describe(description) {
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
   }, {
     key: "validate",
     value: function validate(validationFunction) {
-      return new RecordSchema(this.item, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
   }, {
     key: "executeValidate",
     value: function executeValidate(path, src) {
       var _this2 = this;
       var error = false;
+      if (this.externalLabel !== null) {
+        return this.validateExternal(path, src);
+      }
       var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
@@ -4766,31 +4859,42 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new RecordSchema(this.item, true, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, true, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
+
+    /**
+     * A record you can look at but not change.
+     *
+     * The flag rides in the TYPE as well as in the instance, so `.external()` can
+     * freeze it into the source marker and the adapter's write methods become
+     * required or forbidden on the strength of it. That is also why `.readonly()`
+     * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
+     * there is no `.readonly()` left to call — which is the error the compiler
+     * gives, and a clearer one than a runtime throw.
+     */
   }, {
     key: "readonly",
     value: function readonly() {
       var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
   }, {
     key: "hidden",
     value: function hidden() {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
   }, {
     key: "router",
     value: function router(_router) {
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, _router, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, _router, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
   }, {
     key: "remote",
     value: function remote() {
       return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions ? _objectSpread2(_objectSpread2({}, this.mediaOptions), {}, {
         remote: true
-      }) : undefined, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput);
+      }) : undefined, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
 
     /**
@@ -4832,7 +4936,84 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
       // Empty by construction: the guard above rejects any that were registered.
       [], this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, true,
       // Null by construction: the guard above rejects any that was declared.
-      null, this.renderInput);
+      null, this.renderInput, this.externalLabel);
+    }
+
+    /**
+     * Store this record's entries behind an adapter — a database, an HTTP API, a
+     * bucket — instead of in the module.
+     *
+     * Available on every record-derived schema, which is `s.record()`,
+     * `s.router()`, `s.images()` and `s.files()` alike: a router is a
+     * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
+     * four get external storage from this one method.
+     *
+     * `label` does not address the binding — the registry is keyed by module, and
+     * so is the wire protocol. It exists so a reader of the schema can see what
+     * backs it, and it is checked against the binding that claims it, so the two
+     * cannot drift.
+     *
+     * Only supported on a module's ROOT record, exactly as `.jsonValues()` is: a
+     * nested external record would leave a hole in the middle of a module's
+     * source, and the Studio, patching and validation all assume a module's
+     * source is complete apart from its entries.
+     */
+  }, {
+    key: "external",
+    value: function external(label) {
+      if (this.isJsonValues) {
+        throw new Error(".external() cannot be combined with .jsonValues(): entries live in one place or the other, not both.");
+      }
+      if (!label) {
+        throw new Error('.external() requires a label, e.g. .external("posts")');
+      }
+      return new RecordSchema(this.item, this.opt,
+      // Empty by construction: a validator declared before `.external()` is
+      // typed against the un-external source shape and cannot be carried over.
+      [], this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, null, this.renderInput, label);
+    }
+
+    /**
+     * An external record's source is either the `c.external()` marker or entries
+     * still written inline in the `.val.ts`.
+     *
+     * Inline entries are NOT a type error (see `ExternalRecordWritableSrc`), so
+     * this is where they surface: as an `external:upload` fix, per key, the way
+     * `.jsonValues()` reports an un-extracted entry. Reporting per key rather than
+     * once for the record is what lets the fix be applied to one entry, and what
+     * puts the error at a path the editor can navigate to.
+     */
+  }, {
+    key: "validateExternal",
+    value: function validateExternal(path, src) {
+      if (this.opt && (src === null || src === undefined)) {
+        return false;
+      }
+      if (src === null || _typeof(src) !== "object" || Array.isArray(src)) {
+        return _defineProperty({}, path, [{
+          message: "Expected the c.external() marker or inline entries, got '".concat(src === null ? "null" : Array.isArray(src) ? "array" : _typeof(src), "'"),
+          value: src,
+          schemaError: true
+        }]);
+      }
+      if (isExternal(src)) {
+        // The marker: the entries are the adapter's, and there is nothing here to
+        // check. Their content is validated as it is read.
+        return false;
+      }
+      var error = false;
+      for (var _i = 0, _Object$keys = Object.keys(src); _i < _Object$keys.length; _i++) {
+        var _key = _Object$keys[_i];
+        var subPath = createValPathOfItem(path, _key);
+        if (!subPath) {
+          continue;
+        }
+        error = this.appendValidationError(error, subPath, "Entry is written inline, but this record is .external(\"".concat(this.externalLabel, "\"). Run 'val external upload' to move it into the store."), src[_key]);
+        var errors = error;
+        var last = errors[subPath][errors[subPath].length - 1];
+        last.fixes = ["external:upload"];
+      }
+      return error;
     }
   }, {
     key: "getRouterValidations",
@@ -4886,7 +5067,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "executeSerialize",
     value: function executeSerialize() {
-      var _this$renderInput, _this$keySchema, _this$currentRouter, _this$customValidateF;
+      var _this$renderInput, _this$keySchema, _this$currentRouter, _this$customValidateF, _this$externalLabel;
       var result = {
         type: "record",
         render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
@@ -4897,6 +5078,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         router: (_this$currentRouter = this.currentRouter) === null || _this$currentRouter === void 0 ? void 0 : _this$currentRouter.getRouterId(),
         customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         jsonValues: this.isJsonValues ? true : undefined,
+        external: (_this$externalLabel = this.externalLabel) !== null && _this$externalLabel !== void 0 ? _this$externalLabel : undefined,
         readonly: this.isReadonly,
         hidden: this.isHidden,
         description: this.description
@@ -4934,8 +5116,12 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
       if (src === null) {
         return res;
       }
-      for (var _key in src) {
-        var itemSrc = src[_key];
+      if (isExternal(src)) {
+        // The entries are the adapter's; there is nothing here to preview.
+        return res;
+      }
+      for (var _key2 in src) {
+        var itemSrc = src[_key2];
         if (itemSrc === null || itemSrc === undefined) {
           continue;
         }
@@ -4946,14 +5132,14 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           // keys, and the caller shows a placeholder for the rest.
           continue;
         }
-        var subPath = unsafeCreateSourcePath(sourcePath, _key);
+        var subPath = unsafeCreateSourcePath(sourcePath, _key2);
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
         var itemResult = this.item["executePreview"](subPath, itemSrc, scope);
         for (var keyS in itemResult) {
-          var _key2 = keyS;
-          res[_key2] = itemResult[_key2];
+          var _key3 = keyS;
+          res[_key3] = itemResult[_key3];
         }
       }
       // The entries preview comes from the ITEM schema's own `preview` — the
@@ -4964,9 +5150,9 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         // is being shown, only the wanted entries when it is not.
         var window = scope !== undefined && !scope.wants(sourcePath) ? scope : null;
         var items = [];
-        for (var _i = 0, _Object$entries = Object.entries(src); _i < _Object$entries.length; _i++) {
-          var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
-            _key3 = _Object$entries$_i[0],
+        for (var _i2 = 0, _Object$entries = Object.entries(src); _i2 < _Object$entries.length; _i2++) {
+          var _Object$entries$_i = _slicedToArray(_Object$entries[_i2], 2),
+            _key4 = _Object$entries$_i[0],
             val = _Object$entries$_i[1];
           if (isJson(val)) {
             continue; // as above: nothing to select from an un-loaded entry
@@ -4974,7 +5160,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           if (val === null || val === undefined) {
             continue;
           }
-          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key3))) {
+          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key4))) {
             continue;
           }
           // Per KEY, not per record: the closure is user code, and one entry whose
@@ -4986,14 +5172,14 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
               var title = _item.title,
                 subtitle = _item.subtitle,
                 image = _item.image;
-              items.push([_key3, {
+              items.push([_key4, {
                 title: title,
                 subtitle: subtitle,
                 image: image
               }]);
             }
           } catch (e) {
-            res[unsafeCreateSourcePath(sourcePath, _key3)] = {
+            res[unsafeCreateSourcePath(sourcePath, _key4)] = {
               status: "error",
               message: e instanceof Error ? e.message : "Unknown error"
             };
@@ -5034,7 +5220,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "preview",
     value: function preview(select) {
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, select, this.renderInput);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, select, this.renderInput, this.externalLabel);
     }
 
     /**
@@ -5047,7 +5233,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "render",
     value: function render(input) {
-      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, input);
+      return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, input, this.externalLabel);
     }
   }]);
 }(Schema);
@@ -5548,6 +5734,22 @@ function settings() {
   });
 }
 
+/**
+ * What may be WRITTEN as an external record's source, on top of the marker.
+ *
+ * Entries inline in the `.val.ts` are accepted on purpose — the same call
+ * `.jsonValues()` makes for the same reason: pasting content straight into the
+ * module is the natural first thing to write, and a type error there is a dead
+ * end, because the author cannot see what to write instead. Validation reports
+ * them as an `external:upload` fix, and they are readable at runtime meanwhile.
+ *
+ * Widened HERE rather than in the schema's own source type so that the MODULE
+ * stays typed on the marker alone. An adapter is bound to a module, and a module
+ * whose type were "marker or plain record" would be indistinguishable from an
+ * ordinary record — which would let `entry()` accept a module that is not
+ * external at all.
+ */
+
 function define(id,
 // TODO: `/${string}`
 schema, source) {
@@ -6955,6 +7157,8 @@ function file(options) {
 /**
  * Define a collection of files.
  *
+ * Remote is off by default: call `.remote()` on the result to allow remote files.
+ *
  * @example
  * ```typescript
  * const schema = s.files({
@@ -6969,7 +7173,6 @@ function file(options) {
  * ```
  */
 var files = function files(options) {
-  var _options$remote;
   var directory = options.directory;
   var itemSchema = new ObjectSchema({
     mimeType: new StringSchema({}, false)
@@ -6978,7 +7181,7 @@ var files = function files(options) {
     type: "files",
     accept: options.accept,
     directory: directory,
-    remote: (_options$remote = options.remote) !== null && _options$remote !== void 0 ? _options$remote : false
+    remote: false
   });
 };
 
@@ -8346,7 +8549,7 @@ function router(router, keyOrItem, maybeItem) {
  *
  * `directory` is required — it decides where uploads land, so it is not something
  * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
- * text, remote disabled.
+ * text, remote disabled. Call `.remote()` on the result to allow remote images.
  *
  * @example
  * ```typescript
@@ -8366,7 +8569,7 @@ function router(router, keyOrItem, maybeItem) {
  * ```
  */
 var images = function images(options) {
-  var _options$alt, _options$accept, _options$remote;
+  var _options$alt, _options$accept;
   var directory = options.directory;
   var altSchema = (_options$alt = options.alt) !== null && _options$alt !== void 0 ? _options$alt : string().nullable();
   var itemSchema = new ObjectSchema({
@@ -8379,7 +8582,7 @@ var images = function images(options) {
     type: "images",
     accept: (_options$accept = options.accept) !== null && _options$accept !== void 0 ? _options$accept : "image/*",
     directory: directory,
-    remote: (_options$remote = options.remote) !== null && _options$remote !== void 0 ? _options$remote : false,
+    remote: false,
     altSchema: altSchema,
     encode: options.encode
   });
@@ -8457,7 +8660,8 @@ var initVal = function initVal(config) {
     },
     c: {
       define: define,
-      json: json
+      json: json,
+      external: external
     },
     s: s,
     config: config
@@ -9254,9 +9458,10 @@ function _extractValModules() {
  * The one answer to that question. There used to be two — `hasRemoteFileSchema`
  * in the server, gating whether `/save` demands remote credentials, and
  * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
- * and they disagreed about `s.images({ remote: true })`: the Studio's counted a
- * remote media record, the server's did not, because a media collection
- * serializes as a `record` of metadata rather than as an image schema.
+ * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * counted a remote media record, the server's did not, because a media
+ * collection serializes as a `record` of metadata rather than as an image
+ * schema.
  *
  * The server's answer was the wrong one, and silently so. With it false,
  * `/save` runs `saveOrUploadFiles` in `skip-remote` mode, and that mode does not
@@ -9349,6 +9554,85 @@ function hasRemoteFileSchema(schema) {
   }
 }
 
+/**
+ * Does this schema hold any media at all — remote or not?
+ *
+ * The sibling of {@link hasRemoteFileSchema}, and the same walk minus the
+ * `remote` predicate. It answers the question an external record has to ask
+ * before it will accept a binding: an item schema containing media needs a
+ * `putFile`/`getFile` pair, and without one that is a schema error.
+ *
+ * It is a walk over the SERIALIZED schema for the reasons given above, and for
+ * one more that is specific to this question: the two cases most likely to be
+ * missed are invisible to a value type. A media collection (`s.images()` /
+ * `s.files()`) serializes as a record of metadata with no image schema inside
+ * it, and a richtext inline image lives in a constructor argument. A check
+ * written against the item TYPE would silently pass both — and the gallery case
+ * already has a data-loss incident attached to it (see above).
+ */
+function hasMediaSchema(schema) {
+  if (schema.type === "file" || schema.type === "image") {
+    return true;
+  } else if (schema.type === "richtext") {
+    var _schema$options2;
+    // `img` is `boolean | SerializedImageSchema`: `true` means inline images are
+    // allowed with the DEFAULT image schema, and is just as much media as a
+    // spelled-out one. `hasRemoteFileSchema` tests only for an object because a
+    // default image is not remote — a different question with a different
+    // answer, which is why these two walks are separate functions.
+    if ((_schema$options2 = schema.options) !== null && _schema$options2 !== void 0 && _schema$options2.img) {
+      return true;
+    }
+    return false;
+  } else if (schema.type === "array") {
+    return hasMediaSchema(schema.item);
+  } else if (schema.type === "record") {
+    // A media collection names its file by the record's KEY, so there is no
+    // image schema inside to find: `mediaType` is where the answer is written.
+    if (schema.mediaType) {
+      return true;
+    }
+    return hasMediaSchema(schema.item);
+  } else if (schema.type === "object") {
+    for (var key in schema.items) {
+      if (hasMediaSchema(schema.items[key])) {
+        return true;
+      }
+    }
+    return false;
+  } else if (schema.type === "union") {
+    var unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
+    if (unionObjectSchema) {
+      var _iterator2 = result._createForOfIteratorHelper(unionObjectSchema.items),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var item = _step2.value;
+          if (hasMediaSchema(item)) {
+            return true;
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+    // A string union's items are literals, so there is nothing to look inside.
+    return false;
+  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" ||
+  // A settings module holds the assistant's configuration, not content, and
+  // nothing in it is media.
+  schema.type === "settings") {
+    return false;
+  } else {
+    // Same contract as above: adding a schema type without teaching this
+    // function about it must not compile.
+    var exhaustiveCheck = schema;
+    throw new Error("Unexpected schema: ".concat(JSON.stringify(exhaustiveCheck)));
+  }
+}
+
 var DEFAULT_VAL_REMOTE_HOST = "https://remote.val.build";
 
 var PatchError = /*#__PURE__*/_createClass(function PatchError(message) {
@@ -9493,6 +9777,79 @@ function mediaPathOf(value) {
   return typeof path === "string" ? path : null;
 }
 
+/**
+ * The reference stored for a file whose bytes live behind an external adapter.
+ *
+ * Deliberately the same shape of idea as a remote ref (`remote/splitRemoteRef`):
+ * a URL-ish string that **ends with the file's virtual path**, so the file's
+ * logical identity survives wherever its bytes happen to be.
+ *
+ *     /api/val/external/documents/f/{fileHash}/p/public/val/documents/report_a1b2c.pdf
+ *      \__________________________/ \________/   \_______________________________/
+ *              route + label          content        the path a LOCAL file
+ *                                     address        would have had
+ *
+ * Three things follow from that shape, and each is load-bearing:
+ *
+ * - **`media.ts` needs no change.** `isRemote` is `!path.startsWith("/public")`,
+ *   and this does not, so `Internal.mediaUrl` returns the ref as-is and Val's
+ *   route serves it. The media rule that has been got wrong repeatedly is left
+ *   exactly alone.
+ * - **Moving between storage modes is mechanical.** External → local reads the
+ *   `public/…` suffix back out, fetches the bytes and writes them there; local →
+ *   external uploads the file already at that path. Nothing is renamed.
+ * - **The filename is Val's, not the adapter's**, produced by the same
+ *   `createFilename` a local or remote file uses — so the same bytes get the
+ *   same name under all three storage modes.
+ */
+
+var RegEx = /^\/api\/val\/external\/([^/]+)\/f\/([^/]+)\/p\/(.+)$/;
+function createExternalFileRef(_ref) {
+  var label = _ref.label,
+    fileHash = _ref.fileHash,
+    filePath = _ref.filePath;
+  var withoutLeadingSlash = filePath.startsWith("/") ? filePath.slice(1) : filePath;
+  if (!withoutLeadingSlash.startsWith("public/")) {
+    throw new Error("External file paths must be under '/public', got: '".concat(filePath, "'"));
+  }
+  return "/api/val/external/".concat(label, "/f/").concat(fileHash, "/p/").concat(withoutLeadingSlash);
+}
+function splitExternalFileRef(ref) {
+  var match = ref.match(RegEx);
+  if (!match) {
+    return {
+      status: "error",
+      error: "Not an external file ref: " + ref
+    };
+  }
+  var filePath = match[3];
+  if (!filePath.startsWith("public/")) {
+    return {
+      status: "error",
+      error: "Invalid external file ref: " + ref
+    };
+  }
+  // Traversal check, for the same reason `splitRemoteRef` has one: this path is
+  // used to read and write files.
+  if (filePath.split("/").some(function (segment) {
+    return segment === "." || segment === "..";
+  })) {
+    return {
+      status: "error",
+      error: "Invalid external file ref: " + ref
+    };
+  }
+  return {
+    status: "success",
+    label: match[1],
+    fileHash: match[2],
+    filePath: filePath
+  };
+}
+function isExternalFileRef(ref) {
+  return RegEx.test(ref);
+}
+
 // NOTE: the segments must match the ref built by createRemoteRef below and the RegEx in splitRemoteRef.
 
 function createRemoteRef(remoteHost, _ref) {
@@ -9553,7 +9910,7 @@ function deserializeSchema(serialized) {
   return schema;
 }
 function deserializeSchemaImpl(serialized) {
-  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$accept, _serialized$directory, _serialized$remote, _serialized$jsonValue, _serialized$render9, _serialized$render0, _serialized$render10, _serialized$render11, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15;
+  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$accept, _serialized$directory, _serialized$remote, _serialized$jsonValue, _serialized$render9, _serialized$external, _serialized$render0, _serialized$render10, _serialized$render11, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15;
   switch (serialized.type) {
     case "string":
       return new StringSchema(_objectSpread2(_objectSpread2({}, serialized.options), {}, {
@@ -9614,7 +9971,10 @@ function deserializeSchemaImpl(serialized) {
         altSchema: serialized.alt ? deserializeSchema(serialized.alt) : undefined
       } : undefined, false, false, serialized.description, (_serialized$jsonValue = serialized.jsonValues) !== null && _serialized$jsonValue !== void 0 ? _serialized$jsonValue : false,
       // The preview closure cannot survive serialization; the render can.
-      null, (_serialized$render9 = serialized.render) !== null && _serialized$render9 !== void 0 ? _serialized$render9 : null);
+      null, (_serialized$render9 = serialized.render) !== null && _serialized$render9 !== void 0 ? _serialized$render9 : null, // The external label is static data, so it survives serialization and
+      // must be carried back: a deserialized schema that forgot it would walk
+      // an external record as if its entries were local.
+      (_serialized$external = serialized.external) !== null && _serialized$external !== void 0 ? _serialized$external : null);
     case "keyOf":
       return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render0 = serialized.render) !== null && _serialized$render0 !== void 0 ? _serialized$render0 : null);
     case "route":
@@ -10176,6 +10536,11 @@ var Internal = {
   isJson: isJson,
   getJsonImport: getJsonImport,
   resolveJsonValues: resolveJsonValues,
+  isExternal: isExternal,
+  hasInlineExternalEntries: hasInlineExternalEntries,
+  createExternalFileRef: createExternalFileRef,
+  splitExternalFileRef: splitExternalFileRef,
+  isExternalFileRef: isExternalFileRef,
   createValPathOfItem: createValPathOfItem,
   getSHA256Hash: getSHA256Hash,
   initSchema: initSchema,
@@ -10284,6 +10649,7 @@ exports.derefPatch = derefPatch;
 exports.deserializeSchema = deserializeSchema;
 exports.extractValModules = extractValModules;
 exports.getSourcePathFromRoute = getSourcePathFromRoute;
+exports.hasMediaSchema = hasMediaSchema;
 exports.hasRemoteFileSchema = hasRemoteFileSchema;
 exports.initVal = initVal;
 exports.isInlineRender = isInlineRender;