@valbuild/core 0.124.0 → 0.126.0

package/dist/{index-fcd087bd.cjs.dev.js → index-b41b638f.cjs.dev.js}

@@ -464,6 +464,23 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
     _this.isMultiline = isMultiline;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .string()
+   *   .describe("Shown in the browser tab and in search results");
+   * export default c.define("/example.val.ts", schema, "Hello");
+   */
   _inherits(StringSchema, _Schema);
   return _createClass(StringSchema, [{
     key: "describe",
@@ -473,12 +490,24 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
 
     /**
      * @deprecated Use `minLength` instead
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
      */
   }, {
     key: "min",
     value: function min(minLength) {
       return this.minLength(minLength);
     }
+
+    /**
+     * Validate that the string is at least `minLength` characters long.
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
+     */
   }, {
     key: "minLength",
     value: function minLength(_minLength) {
@@ -489,12 +518,24 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
 
     /**
      * @deprecated Use `maxLength` instead
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
      */
   }, {
     key: "max",
     value: function max(maxLength) {
       return this.maxLength(maxLength);
     }
+
+    /**
+     * Validate that the string is at most `maxLength` characters long.
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
+     */
   }, {
     key: "maxLength",
     value: function maxLength(_maxLength) {
@@ -502,6 +543,19 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
         maxLength: _maxLength
       }), this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, this.isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Validate that the string matches `regexp`.
+     *
+     * `message` is what the editor is shown when it does not match. Without one
+     * the error names the pattern, which is rarely what a non-developer needs.
+     *
+     * @example
+     * const schema = s
+     *   .string()
+     *   .regexp(/^[a-z0-9-]+$/, "Lower case letters, digits and dashes only");
+     * export default c.define("/example.val.ts", schema, "my-slug");
+     */
   }, {
     key: "regexp",
     value: function regexp(_regexp, message) {
@@ -510,6 +564,27 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
         regExpMessage: message
       }), this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, this.isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.string().validate((val) =>
+     *   val.trim() === val ? false : "Must not start or end with a space",
+     * );
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -600,6 +675,26 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new StringSchema(this.options, this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Do not stega encode this string.
+     *
+     * Val normally encodes an invisible pointer back to the source into every
+     * string it hands your app, which is what makes click-to-edit work. A raw
+     * string is handed over exactly as written — use it wherever the value is
+     * not rendered as visible text: a slug, a class name, an `id`, a URL,
+     * anything parsed or compared.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   slug: s.string().raw(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   slug: "hello",
+     * });
+     */
   }, {
     key: "raw",
     value: function raw() {
@@ -665,6 +760,10 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      *
      * Static configuration, not a callback — see `render.ts`. What a CONTAINER
      * shows for its items is a `preview`, which is a different thing entirely.
+     *
+     * @example
+     * const schema = s.array(s.string().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
   }, {
     key: "render",
@@ -676,6 +775,12 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.string().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
   }, {
     key: "preview",
@@ -736,12 +841,59 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .object({ street: s.string(), city: s.string() })
+   *   .describe("Where the office is — shown on the contact page");
+   * export default c.define("/example.val.ts", schema, {
+   *   street: "Torggata 1",
+   *   city: "Oslo",
+   * });
+   */
   _inherits(ObjectSchema, _Schema);
   return _createClass(ObjectSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ObjectSchema(this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * An object validator is the place for a rule that spans FIELDS — one field
+     * validated on its own belongs on that field's schema, where the error lands
+     * on the field itself.
+     *
+     * @example
+     * const schema = s
+     *   .object({ from: s.number(), to: s.number() })
+     *   .validate((val) =>
+     *     val.from <= val.to ? false : "'from' must not be after 'to'",
+     *   );
+     * export default c.define("/example.val.ts", schema, { from: 1, to: 4 });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -894,6 +1046,16 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: each row edits the object in place, instead of
+     * // navigating to it.
+     * const block = s
+     *   .object({ heading: s.string(), body: s.string() })
+     *   .render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { heading: "Hello", body: "World" },
+     * ]);
      */
   }, {
     key: "render",
@@ -905,6 +1067,14 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -1007,12 +1177,54 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     _this.renderInput = renderInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .array(s.string())
+   *   .describe("Bullet points shown under the heading");
+   * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+   */
   _inherits(ArraySchema, _Schema);
   return _createClass(ArraySchema, [{
     key: "describe",
     value: function describe(description) {
       return new ArraySchema(this.item, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.previewInput, this.renderInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The function is given the whole array. To validate one item, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the item's own row.
+     *
+     * @example
+     * const schema = s.array(s.string()).validate((val) =>
+     *   val.length <= 3 ? false : "At most 3 items",
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -1220,6 +1432,25 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
      * is the item of another container, in search, in references. What its rows
      * show is the ITEM schema's `preview`, not this. Never how the field is
      * edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the ARRAY, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const tags = s.array(s.string()).preview(({ val }) => ({
+     *   title: `${val.length} tags`,
+     * }));
+     * export default c.define("/example.val.ts", s.record(tags), {
+     *   "a-post": ["news", "release"],
+     * });
+     *
+     * @example
+     * // Rows of an array come from the ITEM's preview, not the array's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -1233,6 +1464,12 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.record(s.array(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, {
+     *   "a-post": ["news", "release"],
+     * });
      */
   }, {
     key: "render",
@@ -1267,12 +1504,50 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .literal("hero")
+   *   .describe("The block type — it identifies the variant");
+   * export default c.define("/example.val.ts", schema, "hero");
+   */
   _inherits(LiteralSchema, _Schema);
   return _createClass(LiteralSchema, [{
     key: "describe",
     value: function describe(description) {
       return new LiteralSchema(this.value, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.literal("hero").validate((val) =>
+     *   val === "hero" ? false : "Unknown block type",
+     * );
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -1367,6 +1642,10 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.literal("hero").render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
   }, {
     key: "render",
@@ -1378,6 +1657,12 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.literal("hero").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
   }, {
     key: "preview",
@@ -1426,8 +1711,30 @@ var literal = function literal(value) {
   return new LiteralSchema(value);
 };
 
-var UnionSchema = /*#__PURE__*/function (_Schema) {
-  function UnionSchema(key, items) {
+/** The variant objects a discriminated union on `Key` may be built from. */
+
+/**
+ * At least one variant, so a union with none cannot be written.
+ *
+ * Everything downstream reads the first one where it needs any — `emptyOf`
+ * takes `items[0]` for the value a new entry starts as — and a union with
+ * nothing to select is not a thing an author means. `s.enum` says the same
+ * about its values.
+ */
+
+/** The source type a discriminated union over `T` accepts. */
+
+/**
+ * One of several object shapes, told apart by a tag field.
+ *
+ * Every variant is an object with `key` set to a distinct `s.literal(...)`, and
+ * the value of that field decides which variant a value is. Unlike
+ * {@link EnumSchema} this is a CONTAINER: the variant's fields are the fields
+ * being edited, and everything that walks the schema tree has to descend
+ * through the matching variant.
+ */
+var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
+  function DiscriminatedUnionSchema(key, items) {
     var _this;
     var opt = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
     var customValidateFunctions = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : [];
@@ -1436,8 +1743,8 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     var description = arguments.length > 6 ? arguments[6] : undefined;
     var renderInput = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : null;
     var previewInput = arguments.length > 8 && arguments[8] !== undefined ? arguments[8] : null;
-    _classCallCheck(this, UnionSchema);
-    _this = _callSuper(this, UnionSchema);
+    _classCallCheck(this, DiscriminatedUnionSchema);
+    _this = _callSuper(this, DiscriminatedUnionSchema);
     _this.key = key;
     _this.items = items;
     _this.opt = opt;
@@ -1449,16 +1756,66 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
-  _inherits(UnionSchema, _Schema);
-  return _createClass(UnionSchema, [{
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so it is
+   * where you say what an editor needs to know but the field name cannot carry. It
+   * also travels in the serialized schema, which is what the AI assistant and the
+   * MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+   * const text = s.object({ type: s.literal("text"), body: s.string() });
+   * const schema = s
+   *   .discriminatedUnion("type", hero, text)
+   *   .describe("What this section of the page is");
+   * export default c.define("/example.val.ts", schema, {
+   *   type: "hero",
+   *   title: "Hello",
+   * });
+   */
+  _inherits(DiscriminatedUnionSchema, _Schema);
+  return _createClass(DiscriminatedUnionSchema, [{
     key: "describe",
     value: function describe(description) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and before a
+     * publish.
+     *
+     * The function is given the whole value, whichever variant it took. A rule
+     * that only concerns one variant belongs on that variant's object schema.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const schema = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .validate((val) =>
+     *     val.type === "hero" && !val.title ? "A hero needs a title" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, {
+     *   type: "hero",
+     *   title: "Hello",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "executeValidate",
@@ -1466,142 +1823,135 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
+      /**
+       * A structural error at this path, unless the custom validators already
+       * reported — in which case theirs are the answer and this one is dropped.
+       * Faithful to what `s.union` did; changing it is a separate decision.
+       */
+      var structural = function structural(error) {
+        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [error]);
+      };
       var unknownSrc = src;
       if (this.opt && unknownSrc === null) {
         return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : false;
       }
       if (!this.key) {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Missing required first argument in union",
+        return structural({
+          message: "Missing required first argument in discriminated union",
           schemaError: true
-        }]));
+        });
       }
       var key = this.key;
       if (!Array.isArray(this.items)) {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "A union schema must take more than 1 schema arguments",
+        return structural({
+          message: "A discriminated union schema must take more than 1 schema arguments",
           schemaError: true
-        }]));
+        });
       }
-      if (typeof key === "string") {
-        // tagged union
-        if (this.items.some(function (item) {
-          return !(item instanceof ObjectSchema);
-        })) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Key is a string, so all schema items must be objects",
-            schemaError: true
-          }]));
-        }
-        var objectSchemas = this.items;
-        var serializedSchemas = objectSchemas.map(function (schema) {
-          return schema["executeSerialize"]();
+      if (typeof key !== "string") {
+        return structural({
+          message: "The key of a discriminated union must be a string",
+          schemaError: true
         });
-        var illegalSchemas = serializedSchemas.filter(function (schema) {
-          return !(schema.type === "object") || !(schema.items[key].type === "literal");
+      }
+      if (this.items.some(function (item) {
+        return !(item instanceof ObjectSchema);
+      })) {
+        return structural({
+          message: "All schema items of a discriminated union must be objects",
+          schemaError: true
         });
-        if (illegalSchemas.length > 0) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "All schema items must be objects with a key: ".concat(key, " that is a literal schema. Found: ").concat(JSON.stringify(illegalSchemas, null, 2)),
-            schemaError: true
-          }]));
-        }
-        var serializedObjectSchemas = serializedSchemas;
-        var optionalLiterals = serializedObjectSchemas.filter(function (schema) {
-          return schema.items[key].opt;
+      }
+      var objectSchemas = this.items;
+      var serializedSchemas = objectSchemas.map(function (schema) {
+        return schema["executeSerialize"]();
+      });
+      // `items[key]?` — a variant that OMITS the discriminator is exactly what
+      // this check exists to report, so it must not throw while finding it.
+      var illegalSchemas = serializedSchemas.filter(function (schema) {
+        var _schema$items$key;
+        return !(schema.type === "object") || ((_schema$items$key = schema.items[key]) === null || _schema$items$key === void 0 ? void 0 : _schema$items$key.type) !== "literal";
+      });
+      if (illegalSchemas.length > 0) {
+        return structural({
+          message: "All schema items must be objects with a key: ".concat(key, " that is a literal schema. Found: ").concat(JSON.stringify(illegalSchemas, null, 2)),
+          schemaError: true
         });
-        if (optionalLiterals.length > 1) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Schema cannot have an optional keys: ".concat(key),
-            schemaError: true
-          }]));
-        }
-        if (_typeof(unknownSrc) !== "object") {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Expected an object",
-            typeError: true
-          }]));
-        }
-        var objectSrc = unknownSrc;
-        if (objectSrc[key] === undefined) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Missing required key: ".concat(key),
-            typeError: true
-          }]));
-        }
-        var foundSchemaLiterals = [];
-        var _iterator = result._createForOfIteratorHelper(serializedObjectSchemas),
-          _step;
-        try {
-          for (_iterator.s(); !(_step = _iterator.n()).done;) {
-            var schema = _step.value;
-            var schemaKey = schema.items[key];
-            if (schemaKey.type === "literal") {
-              if (!foundSchemaLiterals.includes(schemaKey.value)) {
-                foundSchemaLiterals.push(schemaKey.value);
-              } else {
-                return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-                  message: "Found duplicate key in schema: ".concat(schemaKey.value),
-                  schemaError: true
-                }]));
-              }
-            }
-          }
-        } catch (err) {
-          _iterator.e(err);
-        } finally {
-          _iterator.f();
-        }
-        var objectSchemaAtKey = objectSchemas.find(function (schema) {
-          return !schema["items"][key]["executeValidate"](path, objectSrc[key]);
+      }
+      var serializedObjectSchemas = serializedSchemas;
+      var optionalLiterals = serializedObjectSchemas.filter(function (schema) {
+        return schema.items[key].opt;
+      });
+      if (optionalLiterals.length > 1) {
+        return structural({
+          message: "Schema cannot have an optional keys: ".concat(key),
+          schemaError: true
         });
-        if (!objectSchemaAtKey) {
-          var keyPath = createValPathOfItem(path, key);
-          if (!keyPath) {
-            throw new Error("Internal error: could not create path at ".concat(!path && typeof path === "string" ? "<empty string>" : path, " at key ").concat(key));
-          }
-          return _defineProperty({}, keyPath, [{
-            message: "Invalid key: \"".concat(key, "\". Value was: \"").concat(objectSrc[key], "\". Valid values: ").concat(serializedObjectSchemas.map(function (schema) {
-              var keySchema = schema.items[key];
-              if (keySchema.type === "literal" && keySchema.value) {
-                return "\"".concat(keySchema.value, "\"");
-              } else {
-                // should not happen here, we already checked this
-                throw new Error("Expected literal schema, got ".concat(JSON.stringify(keySchema, null, 2)));
-              }
-            }).join(", "))
-          }]);
-        }
-        var error = objectSchemaAtKey["executeValidate"](path, objectSrc);
-        if (error) {
-          return error;
-        }
-      } else if (key instanceof LiteralSchema) {
-        if (this.items.some(function (item) {
-          return !(item instanceof LiteralSchema);
-        })) {
-          return _defineProperty({}, path, [{
-            message: "Key is a literal schema, so all schema items must be literals",
-            typeError: true
-          }]);
-        }
-        var literalItems = [key].concat(_toConsumableArray(this.items));
-        if (typeof unknownSrc === "string") {
-          var isMatch = literalItems.some(function (item) {
-            return !item["executeValidate"](path, unknownSrc);
-          });
-          if (!isMatch) {
-            return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-              message: "Union must match one of the following: ".concat(literalItems.map(function (item) {
-                return "\"".concat(item["value"], "\"");
-              }).join(", "))
-            }]));
+      }
+
+      // `typeof null === "object"`, so null has to be named separately or it
+      // reaches `objectSrc[key]` below and throws instead of reporting.
+      if (unknownSrc === null || _typeof(unknownSrc) !== "object") {
+        return structural({
+          message: "Expected an object, got ".concat(unknownSrc === null ? "null" : _typeof(unknownSrc)),
+          typeError: true
+        });
+      }
+      var objectSrc = unknownSrc;
+      if (objectSrc[key] === undefined) {
+        return structural({
+          message: "Missing required key: ".concat(key),
+          typeError: true
+        });
+      }
+      var foundSchemaLiterals = [];
+      var _iterator = result._createForOfIteratorHelper(serializedObjectSchemas),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var schema = _step.value;
+          var schemaKey = schema.items[key];
+          if (schemaKey.type === "literal") {
+            if (!foundSchemaLiterals.includes(schemaKey.value)) {
+              foundSchemaLiterals.push(schemaKey.value);
+            } else {
+              return structural({
+                message: "Found duplicate key in schema: ".concat(schemaKey.value),
+                schemaError: true
+              });
+            }
           }
         }
-      } else {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Expected a string or literal"
-        }]));
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      var objectSchemaAtKey = objectSchemas.find(function (schema) {
+        return !schema["items"][key]["executeValidate"](path, objectSrc[key]);
+      });
+      if (!objectSchemaAtKey) {
+        var keyPath = createValPathOfItem(path, key);
+        if (!keyPath) {
+          throw new Error("Internal error: could not create path at ".concat(!path && typeof path === "string" ? "<empty string>" : path, " at key ").concat(key));
+        }
+        return _defineProperty({}, keyPath, [{
+          message: "Invalid key: \"".concat(key, "\". Value was: \"").concat(objectSrc[key], "\". Valid values: ").concat(serializedObjectSchemas.map(function (schema) {
+            var keySchema = schema.items[key];
+            // The TYPE is the whole test: `s.literal("")` is a valid
+            // discriminator, and a truthiness check threw on it here.
+            if (keySchema.type === "literal") {
+              return "\"".concat(keySchema.value, "\"");
+            } else {
+              // should not happen here, we already checked this
+              throw new Error("Expected literal schema, got ".concat(JSON.stringify(keySchema, null, 2)));
+            }
+          }).join(", "))
+        }]);
+      }
+      var error = objectSchemaAtKey["executeValidate"](path, objectSrc);
+      if (error) {
+        return error;
       }
       return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : false;
     }
@@ -1623,11 +1973,11 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           }])
         };
       }
-      if (!this.key) {
+      if (typeof this.key !== "string" || !this.key) {
         return {
           success: false,
           errors: _defineProperty({}, path, [{
-            message: "Missing required first argument in union schema",
+            message: "Missing required first argument in discriminated union schema",
             schemaError: true
           }])
         };
@@ -1636,135 +1986,68 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
         return {
           success: false,
           errors: _defineProperty({}, path, [{
-            message: "The schema of this value is wrong. Schema is neither a union of literals nor a tagged union (of objects)",
+            message: "The schema of this value is wrong. A discriminated union must have an array of object schemas",
             schemaError: true
           }])
         };
       }
-      if (this.key instanceof LiteralSchema) {
-        var _ref23;
-        var success = false;
-        var errors = {};
-        var _iterator2 = result._createForOfIteratorHelper((_ref23 = [this.key]).concat.apply(_ref23, _toConsumableArray(this.items))),
-          _step2;
-        try {
-          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-            var itemSchema = _step2.value;
-            if (!(itemSchema instanceof LiteralSchema)) {
-              return {
-                success: false,
-                errors: _defineProperty({}, path, [{
-                  message: "Schema of value is a union of string, so all schema items must be literals",
-                  schemaError: true
-                }])
-              };
-            }
-            if (typeof src !== "string") {
-              errors[path] = [{
-                message: "Expected 'string', got '".concat(_typeof(src), "'"),
-                typeError: true
-              }];
-              continue;
-            }
-            var res = itemSchema["executeAssert"](path, src);
-            if (res.success) {
-              success = true;
-              break;
-            } else {
-              for (var _i = 0, _Object$entries = Object.entries(res.errors); _i < _Object$entries.length; _i++) {
-                var _errors5;
-                var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
-                  _key = _Object$entries$_i[0],
-                  value = _Object$entries$_i[1];
-                if (!errors[_key]) {
-                  errors[_key] = [];
-                }
-                (_errors5 = errors[_key]).push.apply(_errors5, _toConsumableArray(value));
-              }
-            }
-          }
-        } catch (err) {
-          _iterator2.e(err);
-        } finally {
-          _iterator2.f();
-        }
-        if (!success) {
-          return {
-            success: false,
-            errors: errors
-          };
-        }
-        return {
-          success: true,
-          data: src
-        };
-      } else if (typeof this.key === "string") {
-        var _success = false;
-        var _errors6 = {};
-        var _iterator3 = result._createForOfIteratorHelper(this.items),
-          _step3;
-        try {
-          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
-            var _itemSchema = _step3.value;
-            var _res = _itemSchema["executeAssert"](path, src);
-            if (_res.success) {
-              _success = true;
-              break;
-            } else {
-              for (var _i2 = 0, _Object$entries2 = Object.entries(_res.errors); _i2 < _Object$entries2.length; _i2++) {
-                var _errors7;
-                var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
-                  _key2 = _Object$entries2$_i[0],
-                  _value = _Object$entries2$_i[1];
-                if (!_errors6[_key2]) {
-                  _errors6[_key2] = [];
-                }
-                (_errors7 = _errors6[_key2]).push.apply(_errors7, _toConsumableArray(_value)); // by appending all type errors, we most likely get a lot of duplicate errors. Currently we believe this is correct though, but should probably be handled in when showing the errors to users
+      var success = false;
+      var errors = {};
+      var _iterator2 = result._createForOfIteratorHelper(this.items),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var itemSchema = _step2.value;
+          var res = itemSchema["executeAssert"](path, src);
+          if (res.success) {
+            success = true;
+            break;
+          } else {
+            for (var _i = 0, _Object$entries = Object.entries(res.errors); _i < _Object$entries.length; _i++) {
+              var _errors4;
+              var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+                _key = _Object$entries$_i[0],
+                value = _Object$entries$_i[1];
+              if (!errors[_key]) {
+                errors[_key] = [];
               }
+              (_errors4 = errors[_key]).push.apply(_errors4, _toConsumableArray(value)); // by appending all type errors, we most likely get a lot of duplicate errors. Currently we believe this is correct though, but should probably be handled in when showing the errors to users
             }
           }
-        } catch (err) {
-          _iterator3.e(err);
-        } finally {
-          _iterator3.f();
         }
-        if (!_success) {
-          return {
-            success: false,
-            errors: _errors6
-          };
-        }
-        return {
-          success: true,
-          data: src
-        };
-      } else {
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      if (!success) {
         return {
           success: false,
-          errors: _defineProperty({}, path, [{
-            message: "The schema of this value is wrong. Schema is neither a union of literals nor a tagged union (of objects)",
-            schemaError: true
-          }])
+          errors: errors
         };
       }
+      return {
+        success: true,
+        data: src
+      };
     }
   }, {
     key: "nullable",
     value: function nullable() {
       // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
-      return new UnionSchema(this.key, this.items, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
     value: function readonly() {
       var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "hidden",
     value: function hidden() {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "executeCustomValidateAt",
@@ -1772,10 +2055,10 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       var errors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
-      // A tagged union's variants share the union's path, so `Internal.resolvePath`
-      // stops here and a variant's OWN validator would never be reached. Dispatch
-      // into the variant this value takes — the union is the only node that knows
-      // which one that is.
+      // A discriminated union's variants share the union's path, so
+      // `Internal.resolvePath` stops here and a variant's OWN validator would
+      // never be reached. Dispatch into the variant this value takes — the union
+      // is the only node that knows which one that is.
       var matched = this.matchedVariant(src);
       if (matched) {
         errors.push.apply(errors, _toConsumableArray(matched["executeCustomValidateAt"](path, src)));
@@ -1784,10 +2067,8 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     }
 
     /**
-     * The variant schema a value takes, for a TAGGED union (string `key`). `null`
-     * for a literal union (its variants are leaves with nothing to descend into) or
-     * when the value matches none of them — a structural error `executeValidate`
-     * already reports.
+     * The variant schema a value takes. `null` when the value matches none of
+     * them — a structural error `executeValidate` already reports.
      */
   }, {
     key: "matchedVariant",
@@ -1804,11 +2085,11 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
         return null;
       }
       var objectSchemas = this.items;
-      var _iterator4 = result._createForOfIteratorHelper(objectSchemas),
-        _step4;
+      var _iterator3 = result._createForOfIteratorHelper(objectSchemas),
+        _step3;
       try {
-        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
-          var item = _step4.value;
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var item = _step3.value;
           if (!(item instanceof ObjectSchema)) {
             continue;
           }
@@ -1818,9 +2099,9 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           }
         }
       } catch (err) {
-        _iterator4.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator4.f();
+        _iterator3.f();
       }
       return null;
     }
@@ -1831,11 +2112,21 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: the row draws the tag selector and the matched
+     * // variant's fields.
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s.discriminatedUnion("type", hero, text).render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
      */
   }, {
     key: "render",
     value: function render(input) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
     }
 
     /**
@@ -1843,13 +2134,24 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
      *
-     * Without one of its own, a tagged union previews as the VARIANT the value
-     * takes — declare `preview` on the member objects and the union dispatches.
+     * Without one of its own, a discriminated union previews as the VARIANT the
+     * value takes — declare `preview` on the member objects and the union
+     * dispatches.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .preview(({ val }) => ({ title: val.type }));
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
      */
   }, {
     key: "preview",
     value: function preview(select) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
     }
   }, {
     key: "executePreviewItem",
@@ -1880,34 +2182,19 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "executeSerialize",
     value: function executeSerialize() {
-      var _this$renderInput2, _this$customValidateF2;
-      if (typeof this.key === "string") {
-        var _this$renderInput, _this$customValidateF;
-        return {
-          type: "union",
-          render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
-          preview: this.previewInput ? true : undefined,
-          key: this.key,
-          items: this.items.map(function (o) {
-            return o["executeSerialize"]();
-          }),
-          opt: this.opt,
-          customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
-          readonly: this.isReadonly,
-          hidden: this.isHidden,
-          description: this.description
-        };
-      }
+      var _this$renderInput, _this$customValidateF;
       return {
-        type: "union",
-        render: (_this$renderInput2 = this.renderInput) !== null && _this$renderInput2 !== void 0 ? _this$renderInput2 : undefined,
+        type: "discriminated-union",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
         preview: this.previewInput ? true : undefined,
-        key: this.key["executeSerialize"](),
+        key: this.key,
+        // Every item is an ObjectSchema — `executeValidate` reports a schema
+        // error for anything else, but the type of `T` cannot say so.
         items: this.items.map(function (o) {
           return o["executeSerialize"]();
         }),
         opt: this.opt,
-        customValidate: this.customValidateFunctions && ((_this$customValidateF2 = this.customValidateFunctions) === null || _this$customValidateF2 === void 0 ? void 0 : _this$customValidateF2.length) > 0,
+        customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         readonly: this.isReadonly,
         hidden: this.isHidden,
         description: this.description
@@ -1920,48 +2207,46 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       if (src === null) {
         return res;
       }
-      if (this.key instanceof LiteralSchema) {
-        return res;
-      }
       var unionKey = this.key;
-      if (typeof unionKey === "string") {
-        var thisSchema = this.items.find(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        function (item) {
-          if (item instanceof ObjectSchema) {
-            var itemKey = item["items"][unionKey];
-            if (itemKey instanceof LiteralSchema) {
-              return _typeof(src) === "object" && unionKey in src && itemKey["value"] === src[unionKey];
-            }
-          }
-          return false;
-        });
-        if (thisSchema) {
-          var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
-          for (var keyS in itemResult) {
-            var _key3 = keyS;
-            res[_key3] = itemResult[_key3];
-          }
-          return res;
-        }
+      if (typeof unionKey !== "string") {
         res[sourcePath] = {
           status: "error",
-          message: "Could not find a matching (object) schema for the union key: ".concat(unionKey)
+          message: "The schema of this value is wrong. Expected the key of a discriminated union to be a string. Got: '".concat(JSON.stringify(unionKey, null, 2), "'")
         };
+        return res;
+      }
+      var thisSchema = this.items.find(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      function (item) {
+        if (item instanceof ObjectSchema) {
+          var itemKey = item["items"][unionKey];
+          if (itemKey instanceof LiteralSchema) {
+            return _typeof(src) === "object" && unionKey in src && itemKey["value"] === src[unionKey];
+          }
+        }
+        return false;
+      });
+      if (thisSchema) {
+        var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
+        for (var keyS in itemResult) {
+          var _key2 = keyS;
+          res[_key2] = itemResult[_key2];
+        }
+        return res;
       }
       res[sourcePath] = {
         status: "error",
-        message: "The schema of this value is wrong. Expected a object union schema, but union key is not a string. Got: '".concat(JSON.stringify(unionKey, null, 2), "'")
+        message: "Could not find a matching (object) schema for the discriminated union key: ".concat(unionKey)
       };
       return res;
     }
   }]);
 }(Schema);
-var union = function union(key) {
-  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key4 = 1; _key4 < _len; _key4++) {
-    objects[_key4 - 1] = arguments[_key4];
+var discriminatedUnion = function discriminatedUnion(key) {
+  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key3 = 1; _key3 < _len; _key3++) {
+    objects[_key3 - 1] = arguments[_key3];
   }
-  return new UnionSchema(key, objects);
+  return new DiscriminatedUnionSchema(key, objects);
 };
 
 var RegEx$1 = /^(https?:\/\/[^/]+)\/file\/p\/([^/]+)\/b\/([^/]+)\/v\/([^/]+)\/h\/([^/]+)\/f\/([^/]+)\/p\/(.+)$/;
@@ -2932,17 +3217,94 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .image()
+   *   .describe("Shown at the top of the page, 16:9 works best");
+   * export default c.define("/example.val.ts", schema, {
+   *   path: "/public/val/example.png",
+   *   width: 100,
+   *   height: 100,
+   *   mimeType: "image/png",
+   * });
+   */
   _inherits(ImageSchema, _Schema);
   return _createClass(ImageSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ImageSchema(this.options, this.opt, this.isRemote, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Store the image on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the image is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published image lives: `path` becomes a remote URL rather than a path
+     * under `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote image is a URL on the content host, and it is not
+     * something to write by hand: upload the image in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s
+     *   .image({ accept: "image/webp", directory: "/public/val/images" })
+     *   .remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/example.webp",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/webp",
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
       return new ImageSchema(this.options, this.opt, true, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.image().validate((val) =>
+     *   val.alt ? false : "Every image needs alt text",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     *   alt: "An example",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3160,6 +3522,17 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.image().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *   },
+     * ]);
      */
   }, {
     key: "render",
@@ -3171,6 +3544,23 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.image().preview(({ val }) => ({
+     *     title: val.alt ?? "Image",
+     *     image: val,
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *     alt: "An example",
+     *   },
+     * ]);
      */
   }, {
     key: "preview",
@@ -3267,6 +3657,21 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.route().describe("Where the button goes");
+   * export default c.define("/example.val.ts", schema, "/a-page-slug");
+   */
   _inherits(RouteSchema, _Schema);
   return _createClass(RouteSchema, [{
     key: "describe",
@@ -3313,6 +3718,27 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
         exclude: pattern
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.route().validate((val) =>
+     *   val.endsWith("/") ? "Leave off the trailing slash" : false,
+     * );
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3399,6 +3825,10 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.route().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
   }, {
     key: "render",
@@ -3410,6 +3840,12 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.route().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
   }, {
     key: "preview",
@@ -3490,12 +3926,42 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.richtext().describe("The body of the article");
+   * export default c.define("/example.val.ts", schema, [
+   *   { tag: "p", children: ["Hello"] },
+   * ]);
+   */
   _inherits(RichTextSchema, _Schema);
   return _createClass(RichTextSchema, [{
     key: "describe",
     value: function describe(description) {
       return new RichTextSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the rich text holds at most `max` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
   }, {
     key: "maxLength",
     value: function maxLength(max) {
@@ -3503,6 +3969,19 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         maxLength: max
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the rich text holds at least `min` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().minLength(20).maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Long enough to clear the minimum length."] },
+     * ]);
+     */
   }, {
     key: "minLength",
     value: function minLength(min) {
@@ -3510,6 +3989,29 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         minLength: min
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.richtext().validate((val) =>
+     *   val.length > 0 ? false : "Write something",
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3985,6 +4487,12 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.richtext().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
   }, {
     key: "render",
@@ -3996,6 +4504,16 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.richtext().preview(({ val }) => ({
+     *     title: val.length > 0 ? "Rich text" : "Empty",
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
   }, {
     key: "preview",
@@ -4504,12 +5022,55 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     _this.externalLabel = externalLabel;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .record(s.string())
+   *   .describe("Button labels, keyed by locale");
+   * export default c.define("/example.val.ts", schema, { en: "Read more" });
+   */
   _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, this.externalLabel);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The function is given the whole record. To validate one entry, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the entry's own row, and on a `.jsonValues()` record it does not force
+     * every entry to be loaded.
+     *
+     * @example
+     * const schema = s.record(s.string()).validate((val) =>
+     *   "en" in val ? false : "There has to be an 'en' entry",
+     * );
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -4871,6 +5432,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * 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.
+     *
+     * @example
+     * const schema = s.record(s.string()).readonly();
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
      */
   }, {
     key: "readonly",
@@ -4884,11 +5449,54 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
       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, this.externalLabel);
     }
+
+    /**
+     * Turn this record into a page router: its keys are route paths of your
+     * application, and they are validated against the router's conventions.
+     *
+     * `s.router(router, item)` builds the same thing in one call and is what
+     * most code should use — this is for adding a router to a record that
+     * already exists.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .router(nextAppRouter);
+     * export default c.define("/app/[slug]/page.val.ts", schema, {
+     *   "/a-page-slug": { title: "First Page" },
+     * });
+     */
   }, {
     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, this.externalLabel);
     }
+
+    /**
+     * Allow the files in this gallery to be stored on Val's remote content host
+     * instead of in your repository.
+     *
+     * For `s.images()` and `s.files()`, which are records of media. Remote is off
+     * until this is called.
+     *
+     * Each entry is then keyed by its URL on the content host rather than by a
+     * path under `/public`. That key is not something to write by hand: upload
+     * in the Studio, or add a local path and let `npx val validate --fix`
+     * upload it and rewrite the key.
+     *
+     * @example
+     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * export default c.define("/content/images.val.ts", schema, {
+     *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
+     *     {
+     *       width: 1920,
+     *       height: 1080,
+     *       mimeType: "image/webp",
+     *       alt: "Hero image",
+     *     },
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
@@ -4910,6 +5518,20 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * nested inside an object/array/record is rejected at startup with a module
      * error, because the single-entry fetch endpoint, the Studio's content
      * substitution and content validation are all root-only.
+     *
+     * Must come BEFORE `.validate()` and `.preview()`: those are typed against
+     * the un-lazy source shape, so a validator or preview declared first cannot
+     * be carried over, and declaring one first throws rather than silently
+     * dropping it.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string(), body: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
      */
   }, {
     key: "jsonValues",
@@ -4957,6 +5579,19 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * 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.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     *
+     * @example
+     * // A read-only external record: `.readonly()` must come FIRST, because
+     * // afterwards there is no `.readonly()` left on the type to call.
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .readonly()
+     *   .external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
      */
   }, {
     key: "external",
@@ -5216,6 +5851,25 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * is the item of another container, in search, in references. What its
      * entries show is the ITEM schema's `preview`, not this. Never how the field
      * is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the RECORD, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const labels = s.record(s.string()).preview(({ val }) => ({
+     *   title: `${Object.keys(val).length} locales`,
+     * }));
+     * export default c.define("/example.val.ts", s.array(labels), [
+     *   { en: "Read more" },
+     * ]);
+     *
+     * @example
+     * // Rows of a record come from the ITEM's preview, not the record's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.record(author), {
+     *   ada: { name: "Ada", role: "Engineer" },
+     * });
      */
   }, {
     key: "preview",
@@ -5229,6 +5883,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.record(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [{ en: "Read more" }]);
      */
   }, {
     key: "render",
@@ -5357,12 +6015,48 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.boolean().describe("Show this item in the main menu");
+   * export default c.define("/example.val.ts", schema, true);
+   */
   _inherits(BooleanSchema, _Schema);
   return _createClass(BooleanSchema, [{
     key: "describe",
     value: function describe(description) {
       return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.boolean().validate((val) =>
+     *   val === true ? false : "This has to be on for now",
+     * );
+     * export default c.define("/example.val.ts", schema, true);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -5445,6 +6139,10 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.boolean().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
   }, {
     key: "render",
@@ -5456,6 +6154,12 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.boolean().preview(({ val }) => ({ title: val ? "On" : "Off" })),
+     * );
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
   }, {
     key: "preview",
@@ -5814,10 +6518,8 @@ function isArraySchema(schema) {
 //   );
 // }
 
-function isUnionSchema(schema
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-) {
-  return schema instanceof UnionSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "union";
+function isDiscriminatedUnionSchema(schema) {
+  return schema instanceof DiscriminatedUnionSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "discriminated-union";
 }
 function isRichTextSchema(schema) {
   return schema instanceof RichTextSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "richtext";
@@ -5923,27 +6625,18 @@ function resolvePath(path, valModule, schema) {
             source: resolvedSource
           }
         };
-      } else if (isUnionSchema(resolvedSchema)) {
-        var _key = resolvedSchema.key;
-        if (typeof _key !== "string") {
-          return {
-            v: {
-              path: origParts.map(function (p) {
-                if (!Number.isNaN(Number(p))) {
-                  return p;
-                } else {
-                  return JSON.stringify(p);
-                }
-              }).join("."),
-              // TODO: create a function generate path from parts (not sure if this always works)
-              schema: resolvedSchema,
-              source: resolvedSource
-            }
-          };
+      } else if (isDiscriminatedUnionSchema(resolvedSchema)) {
+        var _key = resolvedSchema instanceof DiscriminatedUnionSchema ? resolvedSchema["key"] : resolvedSchema.key;
+        // A nullable union holding `null` has no variant to descend into, and
+        // `null[key]` throws before any of the reporting below can run.
+        if (resolvedSource === null || _typeof(resolvedSource) !== "object") {
+          throw Error("Schema type error: expected discriminated union source to be an object, but got ".concat(resolvedSource === null ? "null" : _typeof(resolvedSource), " in path: ").concat(path));
         }
         var keyValue = resolvedSource[_key];
-        if (!keyValue) {
-          throw Error("Invalid path: union source ".concat(resolvedSchema, " did not have required key ").concat(_key, " in path: ").concat(path));
+        // `undefined`, not falsy: `s.literal("")` is a legal tag, and a variant
+        // carrying it was reported as a missing key.
+        if (keyValue === undefined) {
+          throw Error("Invalid path: discriminated union source ".concat(resolvedSchema, " did not have required key ").concat(_key, " in path: ").concat(path));
         }
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         var schemaOfUnionKey = resolvedSchema.items.find(
@@ -5953,7 +6646,7 @@ function resolvePath(path, valModule, schema) {
           return (child === null || child === void 0 || (_child$items = child.items) === null || _child$items === void 0 || (_child$items = _child$items[_key]) === null || _child$items === void 0 ? void 0 : _child$items.value) === keyValue;
         });
         if (!schemaOfUnionKey) {
-          throw Error("Invalid path: union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key, " of value ").concat(keyValue, " in path: ").concat(path));
+          throw Error("Invalid path: discriminated union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key, " of value ").concat(keyValue, " in path: ").concat(path));
         }
         resolvedSchema = schemaOfUnionKey.items[part];
         resolvedSource = resolvedSource[part];
@@ -6173,31 +6866,25 @@ function safeResolvePath(path, valModule, schema) {
             source: resolvedSource
           }
         };
-      } else if (isUnionSchema(resolvedSchema)) {
-        var _key2 = resolvedSchema.key;
-        if (typeof _key2 !== "string") {
+      } else if (isDiscriminatedUnionSchema(resolvedSchema)) {
+        var _key2 = resolvedSchema instanceof DiscriminatedUnionSchema ? resolvedSchema["key"] : resolvedSchema.key;
+        // See the note in `resolvePath`: a null union has no variant to descend
+        // into, and this API promises a structured error rather than a throw.
+        if (resolvedSource === null || _typeof(resolvedSource) !== "object") {
           return {
             v: {
-              status: "ok",
-              path: origParts.map(function (p) {
-                if (!Number.isNaN(Number(p))) {
-                  return p;
-                } else {
-                  return JSON.stringify(p);
-                }
-              }).join("."),
-              // TODO: create a function generate path from parts (not sure if this always works)
-              schema: resolvedSchema,
-              source: resolvedSource
+              status: "error",
+              message: "Schema type error: expected discriminated union source to be an object, but got ".concat(resolvedSource === null ? "null" : _typeof(resolvedSource), " in path: ").concat(path)
             }
           };
         }
         var keyValue = resolvedSource[_key2];
-        if (!keyValue) {
+        // See the note in `resolvePath`: an empty-string tag is a present key.
+        if (keyValue === undefined) {
           return {
             v: {
               status: "error",
-              message: "Invalid path: union source ".concat(resolvedSchema, " did not have required key ").concat(_key2, " in path: ").concat(path)
+              message: "Invalid path: discriminated union source ".concat(resolvedSchema, " did not have required key ").concat(_key2, " in path: ").concat(path)
             }
           };
         }
@@ -6212,7 +6899,7 @@ function safeResolvePath(path, valModule, schema) {
           return {
             v: {
               status: "error",
-              message: "Invalid path: union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key2, " of value ").concat(keyValue, " in path: ").concat(path)
+              message: "Invalid path: discriminated union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key2, " of value ").concat(keyValue, " in path: ").concat(path)
             }
           };
         }
@@ -6349,12 +7036,48 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.number().describe("How many columns the grid uses");
+   * export default c.define("/example.val.ts", schema, 3);
+   */
   _inherits(NumberSchema, _Schema);
   return _createClass(NumberSchema, [{
     key: "describe",
     value: function describe(description) {
       return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.number().validate((val) =>
+     *   Number.isInteger(val) ? false : "Must be a whole number",
+     * );
+     * export default c.define("/example.val.ts", schema, 3);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -6442,6 +7165,14 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the number is at most `max` (inclusive).
+     *
+     * @example
+     * const schema = s.number().max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
   }, {
     key: "max",
     value: function max(_max) {
@@ -6449,6 +7180,14 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
         max: _max
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the number is at least `min` (inclusive).
+     *
+     * @example
+     * const schema = s.number().min(1).max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
   }, {
     key: "min",
     value: function min(_min) {
@@ -6470,6 +7209,10 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.number().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
   }, {
     key: "render",
@@ -6481,6 +7224,12 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.number().preview(({ val }) => ({ title: String(val) })),
+     * );
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
   }, {
     key: "preview",
@@ -6523,11 +7272,363 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     value: function executePreview() {
       return {};
     }
-  }]);
-}(Schema);
-var number = function number(options) {
-  return new NumberSchema(options);
-};
+  }]);
+}(Schema);
+var number = function number(options) {
+  return new NumberSchema(options);
+};
+
+/**
+ * One of a fixed set of strings.
+ *
+ * The values are the schema — there are no member schemas to descend into, so
+ * this is a LEAF, like `s.string()` with a closed domain. That is the whole
+ * difference from {@link DiscriminatedUnionSchema}, and the reason the two are
+ * separate: everything that walks a schema tree has to recurse into a
+ * discriminated union's variants and must not try to recurse into these.
+ */
+var EnumSchema = /*#__PURE__*/function (_Schema) {
+  function EnumSchema(values) {
+    var _this;
+    var opt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    var customValidateFunctions = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+    var isReadonly = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+    var isHidden = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
+    var description = arguments.length > 5 ? arguments[5] : undefined;
+    var renderInput = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : null;
+    var previewInput = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : null;
+    _classCallCheck(this, EnumSchema);
+    _this = _callSuper(this, EnumSchema);
+    _this.values = values;
+    _this.opt = opt;
+    _this.customValidateFunctions = customValidateFunctions;
+    _this.isReadonly = isReadonly;
+    _this.isHidden = isHidden;
+    _this.description = description;
+    _this.renderInput = renderInput;
+    _this.previewInput = previewInput;
+    return _this;
+  }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so it is
+   * where you say what an editor needs to know but the field name cannot carry. It
+   * also travels in the serialized schema, which is what the AI assistant and the
+   * MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .enum("draft", "published")
+   *   .describe("Only published pages are built");
+   * export default c.define("/example.val.ts", schema, "draft");
+   */
+  _inherits(EnumSchema, _Schema);
+  return _createClass(EnumSchema, [{
+    key: "describe",
+    value: function describe(description) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+    }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and before a
+     * publish.
+     *
+     * @example
+     * const schema = s
+     *   .enum("draft", "published")
+     *   .validate((val) =>
+     *     val === "published" ? "Publishing is frozen this week" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "draft");
+     */
+  }, {
+    key: "validate",
+    value: function validate(validationFunction) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "executeValidate",
+    value: function executeValidate(path, src) {
+      var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+      // The custom validators always report, whatever the structural answer is.
+      var errors = customValidationErrors;
+      var unknownSrc = src;
+      if (this.opt && (unknownSrc === null || unknownSrc === undefined)) {
+        return errors.length > 0 ? _defineProperty({}, path, errors) : false;
+      }
+      if (!Array.isArray(this.values) || this.values.length === 0) {
+        errors.push({
+          message: "An enum schema must have at least one value",
+          schemaError: true
+        });
+      } else if (typeof unknownSrc !== "string") {
+        errors.push({
+          message: "Expected 'string', got '".concat(unknownSrc === null ? "null" : _typeof(unknownSrc), "'"),
+          value: src,
+          typeError: true
+        });
+      } else if (!this.values.includes(unknownSrc)) {
+        errors.push({
+          message: "Value must be one of the following: ".concat(this.values.map(function (value) {
+            return "\"".concat(value, "\"");
+          }).join(", ")),
+          value: src
+        });
+      }
+      return errors.length > 0 ? _defineProperty({}, path, errors) : false;
+    }
+  }, {
+    key: "executeAssert",
+    value: function executeAssert(path, src) {
+      if (this.opt && src === null) {
+        return {
+          success: true,
+          data: src
+        };
+      }
+      var errors = {};
+      if (typeof src !== "string") {
+        errors[path] = [{
+          message: "Expected 'string', got '".concat(src === null ? "null" : _typeof(src), "'"),
+          typeError: true
+        }];
+        return {
+          success: false,
+          errors: errors
+        };
+      }
+      if (!Array.isArray(this.values) || this.values.length === 0) {
+        errors[path] = [{
+          message: "An enum schema must have at least one value",
+          schemaError: true
+        }];
+        return {
+          success: false,
+          errors: errors
+        };
+      }
+      if (!this.values.includes(src)) {
+        errors[path] = [{
+          message: "Expected one of ".concat(this.values.map(function (value) {
+            return "'".concat(value, "'");
+          }).join(", "), ", got '").concat(src, "'"),
+          typeError: true
+        }];
+        return {
+          success: false,
+          errors: errors
+        };
+      }
+      return {
+        success: true,
+        data: src
+      };
+    }
+  }, {
+    key: "nullable",
+    value: function nullable() {
+      // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
+      return new EnumSchema(this.values, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "readonly",
+    value: function readonly() {
+      var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "hidden",
+    value: function hidden() {
+      var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "executeCustomValidateAt",
+    value: function executeCustomValidateAt(path, src) {
+      return this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+    }
+
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.enum("draft", "published").render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, ["draft"]);
+     */
+  }, {
+    key: "render",
+    value: function render(input) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+    }
+
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.enum("draft", "published").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["draft"]);
+     */
+  }, {
+    key: "preview",
+    value: function preview(select) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+    }
+  }, {
+    key: "executePreviewItem",
+    value: function executePreviewItem(src) {
+      if (this.previewInput === null) {
+        return null;
+      }
+      return this.previewInput({
+        val: src
+      });
+    }
+  }, {
+    key: "declaresItemPreview",
+    value: function declaresItemPreview() {
+      return this.previewInput !== null;
+    }
+  }, {
+    key: "executeSerialize",
+    value: function executeSerialize() {
+      var _this$renderInput, _this$customValidateF;
+      return {
+        type: "enum",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
+        preview: this.previewInput ? true : undefined,
+        values: _toConsumableArray(this.values),
+        opt: this.opt,
+        customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
+        readonly: this.isReadonly,
+        hidden: this.isHidden,
+        description: this.description
+      };
+    }
+  }, {
+    key: "executePreview",
+    value: function executePreview() {
+      // A leaf: nothing below it to preview.
+      return {};
+    }
+  }]);
+}(Schema);
+
+/**
+ * Define a string that must be one of a fixed set of values.
+ *
+ * Named `enumSchema` rather than `enum` because `enum` is a reserved word and
+ * cannot be a binding name; it is exposed as `s.enum`.
+ */
+var enumSchema = function enumSchema() {
+  for (var _len = arguments.length, values = new Array(_len), _key = 0; _key < _len; _key++) {
+    values[_key] = arguments[_key];
+  }
+  return new EnumSchema(values);
+};
+
+/**
+ * @deprecated Use {@link SerializedDiscriminatedUnionSchema} or
+ * {@link SerializedEnumSchema}. A serialized union is now one or the other,
+ * distinguished by `type` rather than by the shape of `key`.
+ */
+
+/** @deprecated Use {@link SerializedEnumSchema}. */
+
+/** @deprecated Use {@link SerializedDiscriminatedUnionSchema}. */
+
+/**
+ * @deprecated There is no single union schema class any more: name
+ * {@link DiscriminatedUnionSchema} or {@link EnumSchema}. The type parameters
+ * are kept so existing annotations still compile, but only `Src` is used.
+ */
+
+/**
+ * The value type of a list of literal schemas — how `s.union` typed a union of
+ * literals. Inferred from `Schema<infer S>` rather than `LiteralSchema<infer S>`
+ * because a `LiteralSchema` is invariant in its source (its custom validate
+ * functions put it in a parameter position), so `LiteralSchema<"a">` is not
+ * assignable to `LiteralSchema<"a" | "b">`.
+ */
+
+/**
+ * @deprecated Use `s.discriminatedUnion(key, ...objects)` for a tagged union of
+ * objects, or `s.enum("a", "b")` for one of a fixed set of strings.
+ *
+ * One thing does NOT survive the literal form: an enum's values are strings,
+ * so a member literal's own `.validate()` and `.describe()` are dropped rather
+ * than carried over. `s.union(s.literal("a").validate(...), ...)` ran that
+ * validator as part of deciding whether the value matched; `s.enum` has no
+ * member to run. A validator on a single-valued literal could only accept or
+ * reject that one value, which the enum's own value list already decides — but
+ * if you rely on one, keep it by validating the enum itself.
+ *
+ * @example
+ * // was: s.union("type", s.object({ type: s.literal("a"), a: s.string() }))
+ * const schema = s.discriminatedUnion(
+ *   "type",
+ *   s.object({ type: s.literal("a"), a: s.string() }),
+ * );
+ * export default c.define("/example.val.ts", schema, { type: "a", a: "one" });
+ *
+ * @example
+ * // was: s.union(s.literal("a"), s.literal("b"))
+ * const schema = s.enum("a", "b");
+ * export default c.define("/example.val.ts", schema, "a");
+ */
+
+function union(keyOrFirstLiteral) {
+  for (var _len = arguments.length, rest = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    rest[_key - 1] = arguments[_key];
+  }
+  if (typeof keyOrFirstLiteral === "string") {
+    return new DiscriminatedUnionSchema(keyOrFirstLiteral, rest);
+  }
+  // A literal union is an enum: the values ARE the schema, so the literals are
+  // flattened into them. `key` was only ever the first member.
+  var literals = [keyOrFirstLiteral].concat(rest);
+  var values = [];
+  var _iterator = result._createForOfIteratorHelper(literals),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var literal = _step.value;
+      if (!(literal instanceof LiteralSchema)) {
+        throw new Error("s.union: expected either a string key followed by object schemas, or literal schemas. Got: ".concat(JSON.stringify(literal)));
+      }
+      values.push(literal["value"]);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return new EnumSchema(values);
+}
 
 var KeyOfSchema = /*#__PURE__*/function (_Schema) {
   function KeyOfSchema(schema, sourcePath) {
@@ -6552,12 +7653,52 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * import authorsVal from "./authors.val"; // a record module
+   * const schema = s.keyOf(authorsVal).describe("Who wrote this post");
+   * export default c.define("/example.val.ts", schema, "ada");
+   */
   _inherits(KeyOfSchema, _Schema);
   return _createClass(KeyOfSchema, [{
     key: "describe",
     value: function describe(description) {
       return new KeyOfSchema(this.schema, this.sourcePath, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s
+     *   .keyOf(authorsVal)
+     *   .validate((val) =>
+     *     val === "placeholder" ? "Pick a real author" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -6719,6 +7860,11 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(s.keyOf(authorsVal).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
   }, {
     key: "render",
@@ -6730,6 +7876,13 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(
+     *   s.keyOf(authorsVal).preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
   }, {
     key: "preview",
@@ -6846,17 +7999,83 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.file().describe("The PDF offered for download");
+   * export default c.define("/example.val.ts", schema, {
+   *   path: "/public/val/example.pdf",
+   *   mimeType: "application/pdf",
+   * });
+   */
   _inherits(FileSchema, _Schema);
   return _createClass(FileSchema, [{
     key: "describe",
     value: function describe(description) {
       return new FileSchema(this.options, this.opt, this.isRemote, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Store the file on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the file is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published file lives: `path` becomes a remote URL rather than a path under
+     * `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote file is a URL on the content host, and it is not
+     * something to write by hand: upload the file in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s.file({ accept: "application/pdf" }).remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
       return new FileSchema(this.options, this.opt, true, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.file().validate((val) =>
+     *   val.path.endsWith(".pdf") ? false : "Must be a PDF",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7063,6 +8282,12 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.file().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
   }, {
     key: "render",
@@ -7074,6 +8299,14 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.file().preview(({ val }) => ({ title: val.path })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -7207,12 +8440,48 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.date().describe("First day the campaign is live");
+   * export default c.define("/example.val.ts", schema, "2025-06-01");
+   */
   _inherits(DateSchema, _Schema);
   return _createClass(DateSchema, [{
     key: "describe",
     value: function describe(description) {
       return new DateSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.date().validate((val) =>
+     *   val >= "2025-01-01" ? false : "Must be in 2025 or later",
+     * );
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7300,6 +8569,16 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         data: src
       };
     }
+
+    /**
+     * Validate that the date is this date or after (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "from",
     value: function from(_from) {
@@ -7307,6 +8586,16 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         from: _from
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the date is this date or before (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01").to("2025-12-31");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "to",
     value: function to(_to) {
@@ -7345,6 +8634,10 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.date().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
   }, {
     key: "render",
@@ -7356,6 +8649,12 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.date().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
   }, {
     key: "preview",
@@ -7426,12 +8725,56 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.datetime().describe("When the article goes live");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   "2025-06-01T09:00:00.000Z",
+   * );
+   */
   _inherits(DateTimeSchema, _Schema);
   return _createClass(DateTimeSchema, [{
     key: "describe",
     value: function describe(description) {
       return new DateTimeSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.datetime().validate((val) =>
+     *   val.endsWith("Z") ? false : "Must be in UTC",
+     * );
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7551,6 +8894,20 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         data: src
       };
     }
+
+    /**
+     * Validate that the datetime is this datetime or after (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s.datetime().from("2025-01-01T00:00:00Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "from",
     value: function from(_from) {
@@ -7558,6 +8915,23 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         from: _from
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the datetime is this datetime or before (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s
+     *   .datetime()
+     *   .from("2025-01-01T00:00:00Z")
+     *   .to("2025-12-31T23:59:59Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "to",
     value: function to(_to) {
@@ -7596,6 +8970,12 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.datetime().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
   }, {
     key: "render",
@@ -7607,6 +8987,14 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.datetime().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
   }, {
     key: "preview",
@@ -7691,12 +9079,59 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .code({ language: "css" })
+   *   .describe("Injected into the page head — keep it small");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   ".hero { color: red; }",
+   * );
+   */
   _inherits(CodeSchema, _Schema);
   return _createClass(CodeSchema, [{
     key: "describe",
     value: function describe(description) {
       return new CodeSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.code({ language: "json" }).validate((val) => {
+     *   try {
+     *     JSON.parse(val);
+     *     return false;
+     *   } catch {
+     *     return "Must be valid JSON";
+     *   }
+     * });
+     * export default c.define("/example.val.ts", schema, '{ "a": 1 }');
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7776,6 +9211,14 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
   }, {
     key: "render",
@@ -7787,6 +9230,16 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).preview(({ val }) => ({
+     *     title: val.split("\n")[0],
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
   }, {
     key: "preview",
@@ -8337,12 +9790,54 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.color().describe("Background of the hero section");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   "hsl(217.22 91.22% 59.8%)",
+   * );
+   */
   _inherits(ColorSchema, _Schema);
   return _createClass(ColorSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ColorSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s
+     *   .color({ format: "hex" })
+     *   .validate((val) =>
+     *     val === val.toLowerCase() ? false : "Write hex in lower case",
+     *   );
+     * export default c.define("/example.val.ts", schema, "#3b82f6");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -8464,6 +9959,12 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.color().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
   }, {
     key: "render",
@@ -8475,6 +9976,14 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.color().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
   }, {
     key: "preview",
@@ -8603,6 +10112,8 @@ function initSchema() {
     array: array,
     object: object,
     number: number,
+    discriminatedUnion: discriminatedUnion,
+    "enum": enumSchema,
     union: union,
     // oneOf,
     richtext: richtext,
@@ -9521,32 +11032,26 @@ function hasRemoteFileSchema(schema) {
       }
     }
     return false;
-  } else if (schema.type === "union") {
-    var unionStringSchema = _typeof(schema.key) === "object" && schema.key.type === "literal" ? schema : undefined;
-    var unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
-    if (unionStringSchema) {
-      // A string union's items are literals, so there is nothing to look inside.
-      return false;
-    }
-    if (unionObjectSchema) {
-      var _iterator = result._createForOfIteratorHelper(unionObjectSchema.items),
-        _step;
-      try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
-          var item = _step.value;
-          var _hasRemoteFile = hasRemoteFileSchema(item);
-          if (_hasRemoteFile) {
-            return true;
-          }
+  } else if (schema.type === "discriminated-union") {
+    var _iterator = result._createForOfIteratorHelper(schema.items),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var item = _step.value;
+        var _hasRemoteFile = hasRemoteFileSchema(item);
+        if (_hasRemoteFile) {
+          return true;
         }
-      } catch (err) {
-        _iterator.e(err);
-      } finally {
-        _iterator.f();
       }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
     }
     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") {
+  } else if (schema.type === "boolean" ||
+  // An enum's values are strings, so there is nothing to look inside.
+  schema.type === "enum" || 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") {
     return false;
   } else {
     var exhaustiveCheck = schema;
@@ -9600,27 +11105,25 @@ function hasMediaSchema(schema) {
       }
     }
     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;
-          }
+  } else if (schema.type === "discriminated-union") {
+    var _iterator2 = result._createForOfIteratorHelper(schema.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();
       }
+    } 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" ||
+  } else if (schema.type === "boolean" ||
+  // An enum's values are strings, so there is nothing to look inside.
+  schema.type === "enum" || 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") {
@@ -9910,7 +11413,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$external, _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$render8, _serialized$accept, _serialized$directory, _serialized$remote, _serialized$jsonValue, _serialized$render0, _serialized$external, _serialized$render1, _serialized$render11, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15, _serialized$render16;
   switch (serialized.type) {
     case "string":
       return new StringSchema(_objectSpread2(_objectSpread2({}, serialized.options), {}, {
@@ -9944,23 +11447,22 @@ function deserializeSchemaImpl(serialized) {
       return new ArraySchema(deserializeSchema(serialized.item), serialized.opt, [], false, false, serialized.description,
       // The preview closure cannot survive serialization; the render can.
       null, (_serialized$render6 = serialized.render) !== null && _serialized$render6 !== void 0 ? _serialized$render6 : null);
-    case "union":
-      return new UnionSchema(typeof serialized.key === "string" ? serialized.key :
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      deserializeSchema(serialized.key),
-      // TODO: we do not really need any here - right?
+    case "discriminated-union":
+      return new DiscriminatedUnionSchema(serialized.key,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       serialized.items.map(deserializeSchema),
       // TODO: we do not really need any here - right?
       serialized.opt, [], false, false, serialized.description, (_serialized$render7 = serialized.render) !== null && _serialized$render7 !== void 0 ? _serialized$render7 : null);
+    case "enum":
+      return new EnumSchema(serialized.values, serialized.opt, [], false, false, serialized.description, (_serialized$render8 = serialized.render) !== null && _serialized$render8 !== void 0 ? _serialized$render8 : null);
     case "richtext":
       {
-        var _serialized$options3, _serialized$options4, _serialized$options5, _serialized$options6, _serialized$render8;
+        var _serialized$options3, _serialized$options4, _serialized$options5, _serialized$options6, _serialized$render9;
         var deserializedOptions = _objectSpread2(_objectSpread2({}, serialized.options || {}), {}, {
           a: _typeof((_serialized$options3 = serialized.options) === null || _serialized$options3 === void 0 ? void 0 : _serialized$options3.a) === "object" ? deserializeSchema(serialized.options.a) : (_serialized$options4 = serialized.options) === null || _serialized$options4 === void 0 ? void 0 : _serialized$options4.a,
           img: _typeof((_serialized$options5 = serialized.options) === null || _serialized$options5 === void 0 ? void 0 : _serialized$options5.img) === "object" ? deserializeSchema(serialized.options.img) : (_serialized$options6 = serialized.options) === null || _serialized$options6 === void 0 ? void 0 : _serialized$options6.img
         });
-        return new RichTextSchema(deserializedOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render8 = serialized.render) !== null && _serialized$render8 !== void 0 ? _serialized$render8 : null);
+        return new RichTextSchema(deserializedOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render9 = serialized.render) !== null && _serialized$render9 !== void 0 ? _serialized$render9 : null);
       }
     case "record":
       return new RecordSchema(deserializeSchema(serialized.item), serialized.opt, [], null, serialized.key ? deserializeSchema(serialized.key) : null, serialized.mediaType ? {
@@ -9971,33 +11473,33 @@ 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, // The external label is static data, so it survives serialization and
+      null, (_serialized$render0 = serialized.render) !== null && _serialized$render0 !== void 0 ? _serialized$render0 : 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);
+      return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render1 = serialized.render) !== null && _serialized$render1 !== void 0 ? _serialized$render1 : null);
     case "route":
       {
-        var _serialized$render1;
+        var _serialized$render10;
         var routeOptions = serialized.options ? {
           include: serialized.options.include ? new RegExp(serialized.options.include.source, serialized.options.include.flags) : undefined,
           exclude: serialized.options.exclude ? new RegExp(serialized.options.exclude.source, serialized.options.exclude.flags) : undefined
         } : undefined;
-        return new RouteSchema(routeOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render1 = serialized.render) !== null && _serialized$render1 !== void 0 ? _serialized$render1 : null);
+        return new RouteSchema(routeOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render10 = serialized.render) !== null && _serialized$render10 !== void 0 ? _serialized$render10 : null);
       }
     case "file":
-      return new FileSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render10 = serialized.render) !== null && _serialized$render10 !== void 0 ? _serialized$render10 : null);
+      return new FileSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render11 = serialized.render) !== null && _serialized$render11 !== void 0 ? _serialized$render11 : null);
     case "image":
-      return new ImageSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render11 = serialized.render) !== null && _serialized$render11 !== void 0 ? _serialized$render11 : null);
+      return new ImageSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render12 = serialized.render) !== null && _serialized$render12 !== void 0 ? _serialized$render12 : null);
     case "date":
-      return new DateSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render12 = serialized.render) !== null && _serialized$render12 !== void 0 ? _serialized$render12 : null);
+      return new DateSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render13 = serialized.render) !== null && _serialized$render13 !== void 0 ? _serialized$render13 : null);
     case "dateTime":
-      return new DateTimeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render13 = serialized.render) !== null && _serialized$render13 !== void 0 ? _serialized$render13 : null);
+      return new DateTimeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render14 = serialized.render) !== null && _serialized$render14 !== void 0 ? _serialized$render14 : null);
     case "color":
-      return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render14 = serialized.render) !== null && _serialized$render14 !== void 0 ? _serialized$render14 : null);
+      return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render15 = serialized.render) !== null && _serialized$render15 !== void 0 ? _serialized$render15 : null);
     case "code":
-      return new CodeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render15 = serialized.render) !== null && _serialized$render15 !== void 0 ? _serialized$render15 : null);
+      return new CodeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render16 = serialized.render) !== null && _serialized$render16 !== void 0 ? _serialized$render16 : null);
     default:
       {
         var exhaustiveCheck = serialized;
@@ -10206,10 +11708,11 @@ function previewScope(paths) {
  * question, and a disagreement between them is a row you can edit in place but
  * that "add" navigates away from.
  *
- * A tagged union counts as inline when the union itself declares it OR when
- * ANY of its variants does. A page-builder list is `s.array(s.union("type",
- * block, block, ...))` and the natural place to write the render is on the
- * blocks, one per block type — the union is a dispatch, not something the
+ * A discriminated union counts as inline when the union itself declares it OR
+ * when ANY of its variants does. A page-builder list is
+ * `s.array(s.discriminatedUnion("type", block, block, ...))` and the natural
+ * place to write the render is on the blocks, one per block type — the union
+ * is a dispatch, not something the
  * author thinks of as the field. `some` rather than `every` because the row
  * draws the union's own editor (the tag selector plus the matched variant's
  * fields), which handles every variant either way: with `every`, adding one
@@ -10226,7 +11729,7 @@ function isInlineRender(schema) {
   if (((_schema$render = schema.render) === null || _schema$render === void 0 ? void 0 : _schema$render.as) === "inline") {
     return true;
   }
-  if (schema.type === "union") {
+  if (schema.type === "discriminated-union") {
     return schema.items.some(function (item) {
       var _item$render;
       return ((_item$render = item.render) === null || _item$render === void 0 ? void 0 : _item$render.as) === "inline";
@@ -10451,23 +11954,190 @@ function parseNextJsRoutePattern(moduleFilePath) {
   return [];
 }
 
+/**
+ * Parse a TanStack Router route pattern out of a Val module file path.
+ *
+ * TanStack Router's file conventions are not Next's, so this is a different
+ * parser rather than a flag on the one above. A Val module for a route lives
+ * beside the route file and is named the same way — `routes/posts.$postId.tsx`
+ * is served content by `routes/posts.$postId.val.ts` — so the pattern is the
+ * file path with the conventions applied:
+ *
+ * - `.` and `/` both separate segments (`posts.$postId.val.ts` and
+ *   `posts/$postId.val.ts` are the same route)
+ * - `$param` is a dynamic segment, `$` on its own is a splat
+ * - `index` is the directory's own route and contributes no segment
+ * - `route` is a layout for the directory, likewise
+ * - `(group)` folders and `_pathless` layout segments are not in the URL
+ * - a trailing `_` on a segment opts out of nesting and is not in the URL
+ *
+ * The result is expressed in the SAME vocabulary the Next parser uses
+ * (`[param]`, `[...param]`), because everything downstream — validation, the
+ * sitemap, the key inputs in the Studio — is written against that vocabulary
+ * and there is no reason for two.
+ *
+ * - /src/routes/posts.$postId.val.ts -> ["posts", "[postId]"]
+ * - /routes/posts/$postId.val.ts     -> ["posts", "[postId]"]
+ * - /src/routes/index.val.ts         -> []
+ * - /src/routes/files.$.val.ts       -> ["files", "[..._splat]"]
+ * - /src/routes/(app)/_layout.about.val.ts -> ["about"]
+ */
+function parseTanStackRoutePattern(moduleFilePath) {
+  var segments = tanStackRouteSegments(moduleFilePath);
+  if (segments === null) {
+    return [];
+  }
+  return segments;
+}
+
+/**
+ * The segments, or `null` when the path is not a TanStack route module at all.
+ *
+ * Distinct from `parseTanStackRoutePattern`'s empty array, which is a real
+ * answer: the root route `/` has no segments.
+ */
+function tanStackRouteSegments(moduleFilePath) {
+  if (!moduleFilePath || typeof moduleFilePath !== "string") {
+    return null;
+  }
+  var match = moduleFilePath.match(/^(?:\/src)?\/routes\/(.+)\.val\.[tj]sx?$/);
+  if (!match) {
+    return null;
+  }
+  return tanStackSegmentsOfRoutePath(match[1]);
+}
+
+/**
+ * The URL segments of a TanStack route path, given relative to `routes/`.
+ *
+ * Exported because the Studio derives the same pattern from the same file path
+ * and must not disagree with validation about what a route is.
+ */
+function tanStackSegmentsOfRoutePath(routePath) {
+  // `.` is a separator exactly like `/`, so flatten both before looking at any
+  // segment: `posts/$postId.edit` and `posts.$postId.edit` are one route.
+  var rawSegments = routePath.split("/").flatMap(function (part) {
+    return part.split(".");
+  }).filter(function (part) {
+    return part !== "";
+  });
+  var segments = [];
+  var _iterator3 = result._createForOfIteratorHelper(rawSegments),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var rawSegment = _step3.value;
+      // A route group: a folder that organises files without appearing in the URL.
+      if (rawSegment.startsWith("(") && rawSegment.endsWith(")")) {
+        continue;
+      }
+      // A pathless layout route. `_layout` nests its children without adding a
+      // segment; `index`/`route` are the directory's own route and its layout.
+      if (rawSegment.startsWith("_")) {
+        continue;
+      }
+      if (rawSegment === "index" || rawSegment === "route") {
+        continue;
+      }
+      // A trailing `_` opts the segment out of layout nesting; the URL keeps the
+      // name without it.
+      var segment = rawSegment.endsWith("_") ? rawSegment.slice(0, -1) : rawSegment;
+      if (segment === "$") {
+        // A splat. Named `_splat` because that is the param name TanStack gives
+        // it, so `useValRoute(pageVal, params)` can be handed the route's own
+        // params object unchanged.
+        segments.push("[..._splat]");
+        continue;
+      }
+      if (segment.startsWith("$")) {
+        segments.push("[".concat(segment.slice(1), "]"));
+        continue;
+      }
+      segments.push(segment);
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  return segments;
+}
+
+/**
+ * The router for a TanStack Router (and TanStack Start) app.
+ *
+ * Like `nextAppRouter` this does not belong in core — it is here for the same
+ * reason that one is: the serialized schema carries only a router id, so the
+ * thing that turns an id back into a validator has to be somewhere every
+ * consumer can reach.
+ */
+var tanstackRouter = {
+  getRouterId: function getRouterId() {
+    return "tanstack-router";
+  },
+  validate: function validate(moduleFilePath, urlPaths) {
+    var routePattern = parseTanStackRoutePattern(moduleFilePath);
+    var errors = [];
+    var _iterator4 = result._createForOfIteratorHelper(urlPaths),
+      _step4;
+    try {
+      for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+        var urlPath = _step4.value;
+        var validation = validateUrlAgainstPattern(urlPath, routePattern);
+        if (!validation.isValid) {
+          errors.push({
+            error: {
+              message: "URL path \"".concat(urlPath, "\" does not match the route pattern for \"").concat(moduleFilePath, "\""),
+              urlPath: urlPath,
+              expectedPath: validation.expectedPath || null
+            }
+          });
+        }
+      }
+    } catch (err) {
+      _iterator4.e(err);
+    } finally {
+      _iterator4.f();
+    }
+    return errors;
+  }
+};
+
+/**
+ * The routers whose keys are URL paths of THIS site, and how to read the route
+ * pattern a module of each serves.
+ *
+ * Keyed by router id because that is all a serialized schema carries. A router
+ * that is not in here — `external-url-router` today — has keys that are URLs of
+ * somewhere else, so matching this site's pathname against them is meaningless
+ * rather than merely unsupported.
+ */
+var PAGE_ROUTE_PATTERN_PARSERS = {
+  "next-app-router": parseNextJsRoutePattern,
+  "tanstack-router": parseTanStackRoutePattern
+};
+
 /**
  * Given a URL pathname (e.g. "/blogs/blog-1") and all serialized module schemas,
- * finds the matching next-app-router module and returns the module file path
- * and the source path for that route's content.
+ * finds the page-router module that serves that route and returns the module
+ * file path and the source path for that route's content.
  *
  * External routers (e.g. external-url-router) are intentionally skipped.
- * Returns null if no next-app-router module matches the pathname.
+ * Returns null if no page-router module matches the pathname.
  */
 function getSourcePathFromRoute(pathname, schemas) {
   for (var _i = 0, _arr = Object.entries(schemas); _i < _arr.length; _i++) {
     var _arr$_i = _slicedToArray(_arr[_i], 2),
       moduleFilePath = _arr$_i[0],
       schema = _arr$_i[1];
-    if (schema.type !== "record" || schema.router !== "next-app-router") {
+    if (schema.type !== "record" || !schema.router) {
       continue;
     }
-    var routePattern = parseNextJsRoutePattern(moduleFilePath);
+    var parseRoutePattern = PAGE_ROUTE_PATTERN_PARSERS[schema.router];
+    if (!parseRoutePattern) {
+      continue;
+    }
+    var routePattern = parseRoutePattern(moduleFilePath);
     var _validateUrlAgainstPa = validateUrlAgainstPattern(pathname, routePattern),
       isValid = _validateUrlAgainstPa.isValid;
     if (isValid) {
@@ -10482,20 +12152,81 @@ function getSourcePathFromRoute(pathname, schemas) {
   return null;
 }
 
+/**
+ * Whether a router id is one whose keys are routes of this site.
+ *
+ * The same question `getSourcePathFromRoute` asks, exported because the Studio
+ * asks it too — a page router gets the sitemap and the "Pages" menu, an
+ * external one gets a flat list of URLs — and the two must not disagree about
+ * which is which.
+ */
+function isPageRouter(routerId) {
+  return routerId in PAGE_ROUTE_PATTERN_PARSERS;
+}
+
+var corePackageJson = {
+	name: "@valbuild/core",
+	version: "0.126.0",
+	"private": false,
+	description: "Val - supercharged hard-coded content",
+	repository: {
+		type: "git",
+		url: "git+https://github.com/valbuild/val.git"
+	},
+	scripts: {
+		typecheck: "tsc --noEmit",
+		test: "jest",
+		"analyze-trace": "npx tsc -p tsconfig.json --skipLibCheck --generateTrace trace; npx -p @typescript/analyze-trace analyze-trace trace;  npx speedscope trace/trace.json"
+	},
+	main: "dist/valbuild-core.cjs.js",
+	module: "dist/valbuild-core.esm.js",
+	exports: {
+		".": {
+			module: "./dist/valbuild-core.esm.js",
+			"default": "./dist/valbuild-core.cjs.js"
+		},
+		"./fp": {
+			module: "./fp/dist/valbuild-core-fp.esm.js",
+			"default": "./fp/dist/valbuild-core-fp.cjs.js"
+		},
+		"./patch": {
+			module: "./patch/dist/valbuild-core-patch.esm.js",
+			"default": "./patch/dist/valbuild-core-patch.cjs.js"
+		},
+		"./package.json": "./package.json"
+	},
+	types: "dist/valbuild-core.cjs.d.ts",
+	preconstruct: {
+		entrypoints: [
+			"./index.ts",
+			"./fp/index.ts",
+			"./patch/index.ts"
+		],
+		exports: true
+	},
+	devDependencies: {
+		typescript: "^6.0.3"
+	},
+	dependencies: {
+		"ts-toolbelt": "^9.6.0"
+	},
+	files: [
+		"CHANGELOG.md",
+		"dist",
+		"fp/dist",
+		"fp/package.json",
+		"patch/dist",
+		"patch/package.json"
+	]
+};
+
 var ModuleFilePathSep = "?p=";
 var FATAL_ERROR_TYPES = ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];
 var DEFAULT_CONTENT_HOST = "https://content.val.build";
 var DEFAULT_APP_HOST = "https://admin.val.build";
 var Internal = {
   VERSION: {
-    core: function () {
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        return require("../package.json").version;
-      } catch (_unused) {
-        return null;
-      }
-    }()
+    core: corePackageJson.version
   },
   mediaUrl: mediaUrl,
   resolveMedia: resolveMedia,
@@ -10512,6 +12243,7 @@ var Internal = {
   splitModuleFilePathAndModulePath: splitModuleFilePathAndModulePath,
   joinModuleFilePathAndModulePath: joinModuleFilePathAndModulePath,
   nextAppRouter: nextAppRouter,
+  tanstackRouter: tanstackRouter,
   externalPageRouter: externalPageRouter,
   color: {
     parseColor: parseColor,
@@ -10600,7 +12332,7 @@ var Internal = {
 function tryJsonParse(str) {
   try {
     return JSON.parse(str);
-  } catch (_unused2) {
+  } catch (_unused) {
     return str;
   }
 }
@@ -10618,6 +12350,8 @@ exports.DEFAULT_CONTENT_HOST = DEFAULT_CONTENT_HOST;
 exports.DEFAULT_VAL_REMOTE_HOST = DEFAULT_VAL_REMOTE_HOST;
 exports.DateSchema = DateSchema;
 exports.DateTimeSchema = DateTimeSchema;
+exports.DiscriminatedUnionSchema = DiscriminatedUnionSchema;
+exports.EnumSchema = EnumSchema;
 exports.FATAL_ERROR_TYPES = FATAL_ERROR_TYPES;
 exports.FileSchema = FileSchema;
 exports.GenericSelector = GenericSelector;
@@ -10636,7 +12370,6 @@ exports.SETTINGS_MODULE_CONVENTION = SETTINGS_MODULE_CONVENTION;
 exports.Schema = Schema;
 exports.SettingsSchema = SettingsSchema;
 exports.StringSchema = StringSchema;
-exports.UnionSchema = UnionSchema;
 exports.VAL_EXTENSION = VAL_EXTENSION;
 exports._classCallCheck = _classCallCheck;
 exports._createClass = _createClass;
@@ -10653,8 +12386,13 @@ exports.hasMediaSchema = hasMediaSchema;
 exports.hasRemoteFileSchema = hasRemoteFileSchema;
 exports.initVal = initVal;
 exports.isInlineRender = isInlineRender;
+exports.isPageRouter = isPageRouter;
 exports.isRootModuleFilePath = isRootModuleFilePath;
 exports.modules = modules;
+exports.parseNextJsRoutePattern = parseNextJsRoutePattern;
+exports.parseTanStackRoutePattern = parseTanStackRoutePattern;
 exports.previewScope = previewScope;
 exports.resolveSettingsModule = resolveSettingsModule;
 exports.splitModuleFilePathAndModulePath = splitModuleFilePathAndModulePath;
+exports.tanStackSegmentsOfRoutePath = tanStackSegmentsOfRoutePath;
+exports.validateUrlAgainstPattern = validateUrlAgainstPattern;