@valbuild/core 0.121.0 → 0.124.0

package/dist/{index-5fe6fb98.esm.js → index-9c14df37.esm.js}

@@ -1962,7 +1962,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 {
@@ -1970,7 +1970,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",
@@ -4368,6 +4368,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
@@ -4396,6 +4484,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;
@@ -4410,24 +4499,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
       });
@@ -4764,31 +4857,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);
     }
 
     /**
@@ -4830,7 +4934,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",
@@ -4884,7 +5065,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,
@@ -4895,6 +5076,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
@@ -4932,8 +5114,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;
         }
@@ -4944,14 +5130,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
@@ -4962,9 +5148,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
@@ -4972,7 +5158,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
@@ -4984,14 +5170,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"
             };
@@ -5032,7 +5218,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);
     }
 
     /**
@@ -5045,7 +5231,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);
@@ -5546,6 +5732,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) {
@@ -6953,6 +7155,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({
@@ -6967,7 +7171,6 @@ function file(options) {
  * ```
  */
 var files = function files(options) {
-  var _options$remote;
   var directory = options.directory;
   var itemSchema = new ObjectSchema({
     mimeType: new StringSchema({}, false)
@@ -6976,7 +7179,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
   });
 };
 
@@ -8344,7 +8547,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
@@ -8364,7 +8567,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({
@@ -8377,7 +8580,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
   });
@@ -8455,7 +8658,8 @@ var initVal = function initVal(config) {
     },
     c: {
       define: define,
-      json: json
+      json: json,
+      external: external
     },
     s: s,
     config: config
@@ -9252,9 +9456,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
@@ -9347,6 +9552,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 = _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) {
@@ -9491,6 +9775,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) {
@@ -9551,7 +9908,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), {}, {
@@ -9612,7 +9969,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":
@@ -10174,6 +10534,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,
@@ -10238,4 +10603,4 @@ function tryJsonParse(str) {
   }
 }
 
-export { ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, DEFAULT_COLOR_FORMAT as E, FATAL_ERROR_TYPES as F, GenericSelector as G, DateTimeSchema as H, Internal as I, RouteSchema as J, KeyOfSchema as K, RichTextSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, LiteralSchema as Q, RecordSchema as R, Schema as S, deserializeSchema as T, UnionSchema as U, VAL_EXTENSION as V, previewScope as W, isInlineRender as X, getSourcePathFromRoute as Y, _typeof as _, _slicedToArray as a, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, DEFAULT_VAL_REMOTE_HOST as j, derefPatch as k, StringSchema as l, modules as m, ImageSchema as n, FileSchema as o, DateSchema as p, SettingsSchema as q, ASSISTANT_SETTINGS_MAX_LENGTH as r, splitModuleFilePathAndModulePath as s, assistantAvailability as t, SETTINGS_MODULE_CONVENTION as u, isRootModuleFilePath as v, resolveSettingsModule as w, CodeSchema as x, CODE_LANGUAGES as y, COLOR_FORMATS as z };
+export { ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, COLOR_FORMATS as E, FATAL_ERROR_TYPES as F, GenericSelector as G, DEFAULT_COLOR_FORMAT as H, Internal as I, DateTimeSchema as J, KeyOfSchema as K, RouteSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RichTextSchema as Q, RecordSchema as R, Schema as S, LiteralSchema as T, UnionSchema as U, VAL_EXTENSION as V, deserializeSchema as W, previewScope as X, isInlineRender as Y, getSourcePathFromRoute as Z, _typeof as _, _slicedToArray as a, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, assistantAvailability as u, SETTINGS_MODULE_CONVENTION as v, isRootModuleFilePath as w, resolveSettingsModule as x, CodeSchema as y, CODE_LANGUAGES as z };