@valbuild/core 0.124.0 → 0.126.0

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

@@ -462,6 +462,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",
@@ -471,12 +488,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) {
@@ -487,12 +516,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) {
@@ -500,6 +541,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) {
@@ -508,6 +562,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) {
@@ -598,6 +673,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() {
@@ -663,6 +758,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",
@@ -674,6 +773,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",
@@ -734,12 +839,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) {
@@ -892,6 +1044,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",
@@ -903,6 +1065,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",
@@ -1005,12 +1175,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) {
@@ -1218,6 +1430,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",
@@ -1231,6 +1462,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",
@@ -1265,12 +1502,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) {
@@ -1365,6 +1640,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",
@@ -1376,6 +1655,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",
@@ -1424,8 +1709,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] : [];
@@ -1434,8 +1741,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;
@@ -1447,16 +1754,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",
@@ -1464,142 +1821,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 = _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 = _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;
     }
@@ -1621,11 +1971,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
           }])
         };
@@ -1634,135 +1984,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 = _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 = _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 = _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",
@@ -1770,10 +2053,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)));
@@ -1782,10 +2065,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",
@@ -1802,11 +2083,11 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
         return null;
       }
       var objectSchemas = this.items;
-      var _iterator4 = _createForOfIteratorHelper(objectSchemas),
-        _step4;
+      var _iterator3 = _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;
           }
@@ -1816,9 +2097,9 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           }
         }
       } catch (err) {
-        _iterator4.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator4.f();
+        _iterator3.f();
       }
       return null;
     }
@@ -1829,11 +2110,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);
     }
 
     /**
@@ -1841,13 +2132,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",
@@ -1878,34 +2180,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
@@ -1918,48 +2205,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\/(.+)$/;
@@ -2930,17 +3215,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) {
@@ -3158,6 +3520,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",
@@ -3169,6 +3542,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",
@@ -3265,6 +3655,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",
@@ -3311,6 +3716,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) {
@@ -3397,6 +3823,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",
@@ -3408,6 +3838,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",
@@ -3488,12 +3924,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) {
@@ -3501,6 +3967,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) {
@@ -3508,6 +3987,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) {
@@ -3983,6 +4485,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",
@@ -3994,6 +4502,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",
@@ -4502,12 +5020,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) {
@@ -4869,6 +5430,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",
@@ -4882,11 +5447,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() {
@@ -4908,6 +5516,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",
@@ -4955,6 +5577,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",
@@ -5214,6 +5849,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",
@@ -5227,6 +5881,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",
@@ -5355,12 +6013,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) {
@@ -5443,6 +6137,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",
@@ -5454,6 +6152,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",
@@ -5812,10 +6516,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";
@@ -5921,27 +6623,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(
@@ -5951,7 +6644,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];
@@ -6171,31 +6864,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)
             }
           };
         }
@@ -6210,7 +6897,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)
             }
           };
         }
@@ -6347,12 +7034,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) {
@@ -6440,6 +7163,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) {
@@ -6447,6 +7178,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) {
@@ -6468,6 +7207,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",
@@ -6479,6 +7222,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",
@@ -6521,11 +7270,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 = _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) {
@@ -6550,12 +7651,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) {
@@ -6717,6 +7858,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",
@@ -6728,6 +7874,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",
@@ -6844,17 +7997,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) {
@@ -7061,6 +8280,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",
@@ -7072,6 +8297,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",
@@ -7205,12 +8438,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) {
@@ -7298,6 +8567,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) {
@@ -7305,6 +8584,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) {
@@ -7343,6 +8632,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",
@@ -7354,6 +8647,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",
@@ -7424,12 +8723,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) {
@@ -7549,6 +8892,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) {
@@ -7556,6 +8913,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) {
@@ -7594,6 +8968,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",
@@ -7605,6 +8985,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",
@@ -7689,12 +9077,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) {
@@ -7774,6 +9209,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",
@@ -7785,6 +9228,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",
@@ -8335,12 +9788,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) {
@@ -8462,6 +9957,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",
@@ -8473,6 +9974,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",
@@ -8601,6 +10110,8 @@ function initSchema() {
     array: array,
     object: object,
     number: number,
+    discriminatedUnion: discriminatedUnion,
+    "enum": enumSchema,
     union: union,
     // oneOf,
     richtext: richtext,
@@ -9519,32 +11030,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 = _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 = _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;
@@ -9598,27 +11103,25 @@ function hasMediaSchema(schema) {
       }
     }
     return false;
-  } else if (schema.type === "union") {
-    var unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
-    if (unionObjectSchema) {
-      var _iterator2 = _createForOfIteratorHelper(unionObjectSchema.items),
-        _step2;
-      try {
-        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-          var item = _step2.value;
-          if (hasMediaSchema(item)) {
-            return true;
-          }
+  } else if (schema.type === "discriminated-union") {
+    var _iterator2 = _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") {
@@ -9908,7 +11411,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), {}, {
@@ -9942,23 +11445,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 ? {
@@ -9969,33 +11471,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;
@@ -10204,10 +11706,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
@@ -10224,7 +11727,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";
@@ -10449,23 +11952,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 = _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 = _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) {
@@ -10480,20 +12150,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,
@@ -10510,6 +12241,7 @@ var Internal = {
   splitModuleFilePathAndModulePath: splitModuleFilePathAndModulePath,
   joinModuleFilePathAndModulePath: joinModuleFilePathAndModulePath,
   nextAppRouter: nextAppRouter,
+  tanstackRouter: tanstackRouter,
   externalPageRouter: externalPageRouter,
   color: {
     parseColor: parseColor,
@@ -10598,9 +12330,9 @@ var Internal = {
 function tryJsonParse(str) {
   try {
     return JSON.parse(str);
-  } catch (_unused2) {
+  } catch (_unused) {
     return str;
   }
 }
 
-export { ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, COLOR_FORMATS as E, FATAL_ERROR_TYPES as F, GenericSelector as G, DEFAULT_COLOR_FORMAT as H, Internal as I, DateTimeSchema as J, KeyOfSchema as K, RouteSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RichTextSchema as Q, RecordSchema as R, Schema as S, LiteralSchema as T, UnionSchema as U, VAL_EXTENSION as V, deserializeSchema as W, previewScope as X, isInlineRender as Y, getSourcePathFromRoute as Z, _typeof as _, _slicedToArray as a, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, assistantAvailability as u, SETTINGS_MODULE_CONVENTION as v, isRootModuleFilePath as w, resolveSettingsModule as x, CodeSchema as y, CODE_LANGUAGES as z };
+export { parseNextJsRoutePattern as $, ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, COLOR_FORMATS as E, FATAL_ERROR_TYPES as F, GenericSelector as G, DEFAULT_COLOR_FORMAT as H, Internal as I, DateTimeSchema as J, KeyOfSchema as K, RouteSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RichTextSchema as Q, RecordSchema as R, Schema as S, DiscriminatedUnionSchema as T, EnumSchema as U, VAL_EXTENSION as V, LiteralSchema as W, deserializeSchema as X, previewScope as Y, isInlineRender as Z, _typeof as _, _slicedToArray as a, parseTanStackRoutePattern as a0, tanStackSegmentsOfRoutePath as a1, validateUrlAgainstPattern as a2, getSourcePathFromRoute as a3, isPageRouter as a4, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, assistantAvailability as u, SETTINGS_MODULE_CONVENTION as v, isRootModuleFilePath as w, resolveSettingsModule as x, CodeSchema as y, CODE_LANGUAGES as z };