@valbuild/core 0.100.0 → 0.102.0

package/dist/{index-c9241d81.esm.js → index-796fd204.esm.js}

@@ -920,6 +920,7 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
       var _this$options4, _this$options5, _this$options6, _this$customValidateF, _this$customValidateF2;
       return {
         type: "string",
+        render: this.renderInput ? true : undefined,
         options: {
           maxLength: (_this$options4 = this.options) === null || _this$options4 === void 0 ? void 0 : _this$options4.maxLength,
           minLength: (_this$options5 = this.options) === null || _this$options5 === void 0 ? void 0 : _this$options5.minLength,
@@ -945,7 +946,12 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executeRender",
-    value: function executeRender(sourcePath, src) {
+    value: function executeRender(sourcePath, src,
+    // Accepted and unused: a string's render is a static layout hint
+    // (`{as:"textarea"}` / `{as:"code",language}`) with no closure behind it, so
+    // there is nothing a scope could prune. Declared so the signature is uniform
+    // across every schema rather than something a reader has to check.
+    _scope) {
       if (this.renderInput) {
         if (this.renderInput.as === "code") {
           return _defineProperty({}, sourcePath, {
@@ -1158,7 +1164,7 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executeRender",
-    value: function executeRender(sourcePath, src) {
+    value: function executeRender(sourcePath, src, scope) {
       var res = {};
       if (src === null) {
         return res;
@@ -1169,7 +1175,13 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
           continue;
         }
         var subPath = unsafeCreateSourcePath(sourcePath, _key3);
-        var itemResult = this.items[_key3]["executeRender"](subPath, itemSrc);
+        // An object produces no render of its own, so it is pure recursion — and
+        // pruning it is the whole contribution: a field deep in one branch stops
+        // paying for every sibling branch's renders.
+        if (scope !== undefined && !scope.wantsUnder(subPath)) {
+          continue;
+        }
+        var itemResult = this.items[_key3]["executeRender"](subPath, itemSrc, scope);
         for (var keyS in itemResult) {
           var _key4 = keyS;
           res[_key4] = itemResult[_key4];
@@ -1311,6 +1323,7 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
         type: "array",
         item: this.item["executeSerialize"](),
         opt: this.opt,
+        render: this.renderInput ? true : undefined,
         customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         readonly: this.isReadonly,
         hidden: this.isHidden,
@@ -1319,7 +1332,7 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executeRender",
-    value: function executeRender(sourcePath, src) {
+    value: function executeRender(sourcePath, src, scope) {
       var res = {};
       if (src === null) {
         return res;
@@ -1331,7 +1344,10 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
           continue;
         }
         var subPath = unsafeCreateSourcePath(sourcePath, key);
-        var itemResult = this.item["executeRender"](subPath, itemSrc);
+        if (scope !== undefined && !scope.wantsUnder(subPath)) {
+          continue;
+        }
+        var itemResult = this.item["executeRender"](subPath, itemSrc, scope);
         for (var keyS in itemResult) {
           var _key = keyS;
           res[_key] = itemResult[_key];
@@ -1347,34 +1363,51 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
             message: "Unknown layout type: " + layout
           };
         }
-        try {
-          res[sourcePath] = {
-            status: "success",
-            data: {
-              layout: "list",
-              parent: "array",
-              items: src.map(function (val) {
-                // NB NB: display is actually defined by the user
-                var _select = select({
-                    val: val
-                  }),
-                  title = _select.title,
-                  subtitle = _select.subtitle,
-                  image = _select.image;
-                return {
-                  title: title,
-                  subtitle: subtitle,
-                  image: image
-                };
-              })
-            }
-          };
-        } catch (e) {
-          res[sourcePath] = {
-            status: "error",
-            message: e instanceof Error ? e.message : "Unknown error"
-          };
+        // The whole list when the LIST is what is being shown; only the wanted
+        // rows when it is not. `select` is the user's closure and the real expense
+        // — a list view asks for the container and gets every row, a single field
+        // asks for its own path and costs one call.
+        // Non-null once, as a value, rather than a boolean the compiler cannot
+        // tie back to `scope`: no scope and a scope that wants this exact path
+        // both mean the whole list, and anything else is a window.
+        var window = scope !== undefined && !scope.wants(sourcePath) ? scope : null;
+        var items = [];
+        for (var index = 0; index < src.length; index++) {
+          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, index))) {
+            continue;
+          }
+          // Per ITEM, not per list, matching what `record` already does: `select`
+          // is user code, and one row whose data trips it up must not take out the
+          // whole list. Before scoping, one throwing row produced an error at the
+          // container and no items at all.
+          try {
+            // NB NB: display is actually defined by the user
+            var _select = select({
+                val: src[index]
+              }),
+              title = _select.title,
+              subtitle = _select.subtitle,
+              image = _select.image;
+            items.push([index, {
+              title: title,
+              subtitle: subtitle,
+              image: image
+            }]);
+          } catch (e) {
+            res[unsafeCreateSourcePath(sourcePath, index)] = {
+              status: "error",
+              message: e instanceof Error ? e.message : "Unknown error"
+            };
+          }
         }
+        res[sourcePath] = {
+          status: "success",
+          data: {
+            layout: "list",
+            parent: "array",
+            items: items
+          }
+        };
       }
       return res;
     }
@@ -1948,7 +1981,7 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executeRender",
-    value: function executeRender(sourcePath, src) {
+    value: function executeRender(sourcePath, src, scope) {
       var res = {};
       if (src === null) {
         return res;
@@ -1970,7 +2003,7 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           return false;
         });
         if (thisSchema) {
-          var itemResult = thisSchema["executeRender"](sourcePath, src);
+          var itemResult = thisSchema["executeRender"](sourcePath, src, scope);
           for (var keyS in itemResult) {
             var _key3 = keyS;
             res[_key3] = itemResult[_key3];
@@ -3857,6 +3890,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         item: this.item["executeSerialize"](),
         key: (_this$keySchema = this.keySchema) === null || _this$keySchema === void 0 ? void 0 : _this$keySchema["executeSerialize"](),
         opt: this.opt,
+        render: this.renderInput ? true : undefined,
         router: (_this$currentRouter = this.currentRouter) === null || _this$currentRouter === void 0 ? void 0 : _this$currentRouter.getRouterId(),
         customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         jsonValues: this.isJsonValues ? true : undefined,
@@ -3889,7 +3923,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executeRender",
-    value: function executeRender(sourcePath, src) {
+    value: function executeRender(sourcePath, src, scope) {
       var res = {};
       if (src === null) {
         return res;
@@ -3907,7 +3941,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           continue;
         }
         var subPath = unsafeCreateSourcePath(sourcePath, _key);
-        var itemResult = this.item["executeRender"](subPath, itemSrc);
+        if (scope !== undefined && !scope.wantsUnder(subPath)) {
+          continue;
+        }
+        var itemResult = this.item["executeRender"](subPath, itemSrc, scope);
         for (var keyS in itemResult) {
           var _key2 = keyS;
           res[_key2] = itemResult[_key2];
@@ -3923,6 +3960,9 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
             message: "Unknown layout type: " + layout
           };
         }
+        // See the same block in `array`: the whole record when the record is what
+        // is being shown, only the wanted entries when it is not.
+        var window = scope !== undefined && !scope.wants(sourcePath) ? scope : null;
         var items = [];
         for (var _i = 0, _Object$entries = Object.entries(src); _i < _Object$entries.length; _i++) {
           var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
@@ -3931,6 +3971,9 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           if (isJson(val)) {
             continue; // as above: nothing to select from an un-loaded entry
           }
+          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key3))) {
+            continue;
+          }
           // Per KEY, not per record: `select` is user code, and one entry whose
           // data trips it up must not take out the whole list.
           try {
@@ -5063,8 +5106,8 @@ var keyOf = function keyOf(valModule) {
  * ```
  */
 var files = function files(options) {
-  var _options$directory, _options$remote;
-  var directory = (_options$directory = options.directory) !== null && _options$directory !== void 0 ? _options$directory : "/public/val";
+  var _options$remote;
+  var directory = options.directory;
   var itemSchema = new ObjectSchema({
     mimeType: new StringSchema({}, false)
   }, false);
@@ -5452,6 +5495,647 @@ var datetime = function datetime(options) {
   return new DateTimeSchema(options);
 };
 
+/**
+ * Parsing / formatting of the CSS color strings stored by `s.color()`.
+ *
+ * Colors are stored as plain CSS strings so that they can be used directly in
+ * `style` attributes and CSS custom properties. The schema decides which family
+ * (`hex`, `rgb`, `hsl` or `oklch`) the string is written in, this module does
+ * the conversion between them.
+ *
+ * All colors are sRGB: `oklch` is only used as an output notation, so any
+ * `oklch` value that falls outside the sRGB gamut is clipped when converted
+ * back to the other formats.
+ */
+
+var COLOR_FORMATS = ["hex", "rgb", "hsl", "oklch"];
+var DEFAULT_COLOR_FORMAT = "hsl";
+
+/**
+ * A color, normalized to sRGB.
+ *
+ * `r`, `g` and `b` are 0-255 (not rounded), `a` is 0-1.
+ */
+
+/**
+ * Which color notation a string uses, or `null` if it is not a notation we
+ * recognize. This looks at the syntax only: `detectColorFormat` says nothing
+ * about whether the value actually parses (`hsl(nope)` is still `"hsl"`).
+ */
+function detectColorFormat(value) {
+  var trimmed = value.trim().toLowerCase();
+  if (trimmed.startsWith("#")) {
+    return "hex";
+  }
+  if (trimmed.startsWith("rgb(") || trimmed.startsWith("rgba(")) {
+    return "rgb";
+  }
+  if (trimmed.startsWith("hsl(") || trimmed.startsWith("hsla(")) {
+    return "hsl";
+  }
+  if (trimmed.startsWith("oklch(")) {
+    return "oklch";
+  }
+  return null;
+}
+function clamp(value, min, max) {
+  if (Number.isNaN(value)) {
+    return min;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+
+/**
+ * Splits the inside of a CSS color function into components.
+ *
+ * Handles both the legacy comma syntax (`rgb(1, 2, 3, 0.5)`) and the modern
+ * space syntax (`rgb(1 2 3 / 0.5)`), returning the alpha (if any) separately.
+ */
+function splitComponents(args) {
+  var slashParts = args.split("/");
+  if (slashParts.length > 2) {
+    return null;
+  }
+  var alpha = slashParts.length === 2 ? slashParts[1].trim() : null;
+  var head = slashParts[0].trim();
+  if (head === "") {
+    return null;
+  }
+  var components;
+  if (head.includes(",")) {
+    if (alpha !== null) {
+      // Mixing the comma and the slash syntax is not valid CSS
+      return null;
+    }
+    components = head.split(",").map(function (part) {
+      return part.trim();
+    });
+    if (components.length === 4) {
+      alpha = components[3];
+      components = components.slice(0, 3);
+    }
+  } else {
+    components = head.split(/\s+/);
+  }
+  if (components.length !== 3 || components.some(function (part) {
+    return part === "";
+  })) {
+    return null;
+  }
+  if (alpha === "") {
+    return null;
+  }
+  return {
+    components: components,
+    alpha: alpha
+  };
+}
+function parseNumber(value) {
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)$/.test(value)) {
+    return null;
+  }
+  var parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * A `<number>` or a `<percentage>`, where 100% maps to `percentageBasis`.
+ */
+function parseNumberOrPercentage(value, percentageBasis) {
+  if (value.endsWith("%")) {
+    var percentage = parseNumber(value.slice(0, -1));
+    return percentage === null ? null : percentage / 100 * percentageBasis;
+  }
+  return parseNumber(value);
+}
+function parsePercentage(value) {
+  if (!value.endsWith("%")) {
+    return null;
+  }
+  return parseNumber(value.slice(0, -1));
+}
+function parseAlpha(value) {
+  if (value === null) {
+    return 1;
+  }
+  if (value === "none") {
+    return 0;
+  }
+  var parsed = parseNumberOrPercentage(value, 1);
+  return parsed === null ? null : clamp(parsed, 0, 1);
+}
+function parseHue(value) {
+  var match = /^([+-]?(?:\d+\.?\d*|\.\d+))(deg|grad|rad|turn)?$/.exec(value);
+  if (!match) {
+    return null;
+  }
+  var amount = Number(match[1]);
+  switch (match[2]) {
+    case "grad":
+      return amount / 400 * 360;
+    case "rad":
+      return amount * 180 / Math.PI;
+    case "turn":
+      return amount * 360;
+    default:
+      return amount;
+  }
+}
+function normalizeHue(hue) {
+  var wrapped = hue % 360;
+  return wrapped < 0 ? wrapped + 360 : wrapped;
+}
+function parseHex(value) {
+  var hex = value.slice(1);
+  if (!/^[0-9a-f]+$/i.test(hex)) {
+    return null;
+  }
+  var expand = function expand(_char) {
+    return parseInt(_char + _char, 16);
+  };
+  var pair = function pair(index) {
+    return parseInt(hex.slice(index, index + 2), 16);
+  };
+  if (hex.length === 3 || hex.length === 4) {
+    return {
+      r: expand(hex[0]),
+      g: expand(hex[1]),
+      b: expand(hex[2]),
+      a: hex.length === 4 ? expand(hex[3]) / 255 : 1
+    };
+  }
+  if (hex.length === 6 || hex.length === 8) {
+    return {
+      r: pair(0),
+      g: pair(2),
+      b: pair(4),
+      a: hex.length === 8 ? pair(6) / 255 : 1
+    };
+  }
+  return null;
+}
+function extractFunctionArgs(value, name) {
+  if (!value.startsWith(name + "(") || !value.endsWith(")")) {
+    return null;
+  }
+  return value.slice(name.length + 1, -1);
+}
+function parseRgb(value) {
+  var _extractFunctionArgs;
+  var args = (_extractFunctionArgs = extractFunctionArgs(value, "rgba")) !== null && _extractFunctionArgs !== void 0 ? _extractFunctionArgs : extractFunctionArgs(value, "rgb");
+  if (args === null) {
+    return null;
+  }
+  var split = splitComponents(args);
+  if (!split) {
+    return null;
+  }
+  var channels = split.components.map(function (component) {
+    return component === "none" ? 0 : parseNumberOrPercentage(component, 255);
+  });
+  var alpha = parseAlpha(split.alpha);
+  if (channels.some(function (channel) {
+    return channel === null;
+  }) || alpha === null) {
+    return null;
+  }
+  return {
+    r: clamp(channels[0], 0, 255),
+    g: clamp(channels[1], 0, 255),
+    b: clamp(channels[2], 0, 255),
+    a: alpha
+  };
+}
+function parseHsl(value) {
+  var _extractFunctionArgs2, _parsePercentage, _parsePercentage2;
+  var args = (_extractFunctionArgs2 = extractFunctionArgs(value, "hsla")) !== null && _extractFunctionArgs2 !== void 0 ? _extractFunctionArgs2 : extractFunctionArgs(value, "hsl");
+  if (args === null) {
+    return null;
+  }
+  var split = splitComponents(args);
+  if (!split) {
+    return null;
+  }
+  var _split$components = _slicedToArray(split.components, 3),
+    rawHue = _split$components[0],
+    rawSaturation = _split$components[1],
+    rawLightness = _split$components[2];
+  var hue = rawHue === "none" ? 0 : parseHue(rawHue);
+  // CSS requires percentages for s/l in hsl(), but the modern syntax also
+  // allows bare numbers, so accept both.
+  var saturation = rawSaturation === "none" ? 0 : (_parsePercentage = parsePercentage(rawSaturation)) !== null && _parsePercentage !== void 0 ? _parsePercentage : parseNumber(rawSaturation);
+  var lightness = rawLightness === "none" ? 0 : (_parsePercentage2 = parsePercentage(rawLightness)) !== null && _parsePercentage2 !== void 0 ? _parsePercentage2 : parseNumber(rawLightness);
+  var alpha = parseAlpha(split.alpha);
+  if (hue === null || saturation === null || lightness === null || alpha === null) {
+    return null;
+  }
+  return _objectSpread2(_objectSpread2({}, hslToRgb(normalizeHue(hue), clamp(saturation, 0, 100), clamp(lightness, 0, 100))), {}, {
+    a: alpha
+  });
+}
+function parseOklch(value) {
+  var args = extractFunctionArgs(value, "oklch");
+  if (args === null) {
+    return null;
+  }
+  var split = splitComponents(args);
+  if (!split) {
+    return null;
+  }
+  var _split$components2 = _slicedToArray(split.components, 3),
+    rawLightness = _split$components2[0],
+    rawChroma = _split$components2[1],
+    rawHue = _split$components2[2];
+  // Lightness is a <number> in 0-1 or a <percentage>, chroma is a <number>
+  // where 0.4 is roughly the maximum, or a <percentage> where 100% = 0.4.
+  var lightness = rawLightness === "none" ? 0 : parseNumberOrPercentage(rawLightness, 1);
+  var chroma = rawChroma === "none" ? 0 : parseNumberOrPercentage(rawChroma, 0.4);
+  var hue = rawHue === "none" ? 0 : parseHue(rawHue);
+  var alpha = parseAlpha(split.alpha);
+  if (lightness === null || chroma === null || hue === null || alpha === null) {
+    return null;
+  }
+  return _objectSpread2(_objectSpread2({}, oklchToRgb(clamp(lightness, 0, 1), Math.max(0, chroma), normalizeHue(hue))), {}, {
+    a: alpha
+  });
+}
+
+/**
+ * Parses a CSS color string into sRGB channels.
+ *
+ * Accepts hex (3, 4, 6 and 8 digits), `rgb()` / `rgba()`, `hsl()` / `hsla()`
+ * and `oklch()`, in both the legacy comma and the modern space syntax. Returns
+ * `null` if the value is not a color we can parse - notably: named colors
+ * (`red`), `color()`, `lab()` and `color-mix()` are not supported.
+ */
+function parseColor(value) {
+  var normalized = value.trim().toLowerCase();
+  if (normalized === "") {
+    return null;
+  }
+  switch (detectColorFormat(normalized)) {
+    case "hex":
+      return parseHex(normalized);
+    case "rgb":
+      return parseRgb(normalized);
+    case "hsl":
+      return parseHsl(normalized);
+    case "oklch":
+      return parseOklch(normalized);
+    default:
+      return null;
+  }
+}
+
+/**
+ * Rounds to at most `decimals` decimals, without trailing zeros.
+ */
+function round(value, decimals) {
+  var factor = Math.pow(10, decimals);
+  // `|| 0` normalizes -0 to 0
+  return Math.round(value * factor) / factor || 0;
+}
+function toHexPair(value) {
+  return clamp(Math.round(value), 0, 255).toString(16).padStart(2, "0");
+}
+function rgbToHsl(r, g, b) {
+  var red = r / 255;
+  var green = g / 255;
+  var blue = b / 255;
+  var max = Math.max(red, green, blue);
+  var min = Math.min(red, green, blue);
+  var delta = max - min;
+  var l = (max + min) / 2;
+  if (delta === 0) {
+    return {
+      h: 0,
+      s: 0,
+      l: l * 100
+    };
+  }
+  var s = delta / (1 - Math.abs(2 * l - 1));
+  var h;
+  if (max === red) {
+    h = (green - blue) / delta % 6;
+  } else if (max === green) {
+    h = (blue - red) / delta + 2;
+  } else {
+    h = (red - green) / delta + 4;
+  }
+  return {
+    h: normalizeHue(h * 60),
+    s: s * 100,
+    l: l * 100
+  };
+}
+function hslToRgb(h, s, l) {
+  var saturation = s / 100;
+  var lightness = l / 100;
+  var c = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  var hPrime = normalizeHue(h) / 60;
+  var x = c * (1 - Math.abs(hPrime % 2 - 1));
+  var m = lightness - c / 2;
+  var rgb;
+  if (hPrime < 1) {
+    rgb = [c, x, 0];
+  } else if (hPrime < 2) {
+    rgb = [x, c, 0];
+  } else if (hPrime < 3) {
+    rgb = [0, c, x];
+  } else if (hPrime < 4) {
+    rgb = [0, x, c];
+  } else if (hPrime < 5) {
+    rgb = [x, 0, c];
+  } else {
+    rgb = [c, 0, x];
+  }
+  return {
+    r: (rgb[0] + m) * 255,
+    g: (rgb[1] + m) * 255,
+    b: (rgb[2] + m) * 255
+  };
+}
+function srgbToLinear(channel) {
+  var c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function linearToSrgb(channel) {
+  var c = channel <= 0.0031308 ? channel * 12.92 : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055;
+  return clamp(c * 255, 0, 255);
+}
+
+/**
+ * sRGB to Oklch, using Björn Ottosson's Oklab matrices.
+ */
+function rgbToOklch(r, g, b) {
+  var lr = srgbToLinear(r);
+  var lg = srgbToLinear(g);
+  var lb = srgbToLinear(b);
+  var _long = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  var medium = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  var _short = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  var lightness = 0.2104542553 * _long + 0.793617785 * medium - 0.0040720468 * _short;
+  var a = 1.9779984951 * _long - 2.428592205 * medium + 0.4505937099 * _short;
+  var bComponent = 0.0259040371 * _long + 0.7827717662 * medium - 0.808675766 * _short;
+  var chroma = Math.sqrt(a * a + bComponent * bComponent);
+  // Achromatic colors have an undefined hue: report 0 rather than the noise
+  // that atan2 of two near-zero numbers produces.
+  var hue = chroma < 1e-6 ? 0 : normalizeHue(Math.atan2(bComponent, a) * 180 / Math.PI);
+  return {
+    l: clamp(lightness, 0, 1),
+    c: chroma,
+    h: hue
+  };
+}
+
+/**
+ * Oklch to sRGB. Out of gamut colors are clipped per channel.
+ */
+function oklchToRgb(l, c, h) {
+  var hueRadians = normalizeHue(h) * Math.PI / 180;
+  var a = c * Math.cos(hueRadians);
+  var bComponent = c * Math.sin(hueRadians);
+  var _long2 = Math.pow(l + 0.3963377774 * a + 0.2158037573 * bComponent, 3);
+  var medium = Math.pow(l - 0.1055613458 * a - 0.0638541728 * bComponent, 3);
+  var _short2 = Math.pow(l - 0.0894841775 * a - 1.291485548 * bComponent, 3);
+  return {
+    r: linearToSrgb(4.0767416621 * _long2 - 3.3077115913 * medium + 0.2309699292 * _short2),
+    g: linearToSrgb(-1.2684380046 * _long2 + 2.6097574011 * medium - 0.3413193965 * _short2),
+    b: linearToSrgb(-0.0041960863 * _long2 - 0.7034186147 * medium + 1.707614701 * _short2)
+  };
+}
+
+/**
+ * Serializes a color to the canonical string of the given format.
+ *
+ * The modern, space separated CSS syntax is used for the color functions
+ * (`rgb(255 0 0 / 0.5)`). Alpha is only included when it is not fully opaque.
+ */
+function formatColor(color, format) {
+  var alpha = clamp(color.a, 0, 1);
+  var alphaSuffix = alpha >= 1 ? "" : " / ".concat(round(alpha, 4));
+  switch (format) {
+    case "hex":
+      {
+        var hex = "#".concat(toHexPair(color.r)).concat(toHexPair(color.g)).concat(toHexPair(color.b));
+        return alpha >= 1 ? hex : "".concat(hex).concat(toHexPair(alpha * 255));
+      }
+    case "rgb":
+      {
+        var r = clamp(Math.round(color.r), 0, 255);
+        var g = clamp(Math.round(color.g), 0, 255);
+        var b = clamp(Math.round(color.b), 0, 255);
+        return "rgb(".concat(r, " ").concat(g, " ").concat(b).concat(alphaSuffix, ")");
+      }
+    case "hsl":
+      {
+        var _rgbToHsl = rgbToHsl(color.r, color.g, color.b),
+          h = _rgbToHsl.h,
+          s = _rgbToHsl.s,
+          l = _rgbToHsl.l;
+        return "hsl(".concat(round(h, 2), " ").concat(round(s, 2), "% ").concat(round(l, 2), "%").concat(alphaSuffix, ")");
+      }
+    case "oklch":
+      {
+        var _rgbToOklch = rgbToOklch(color.r, color.g, color.b),
+          _l = _rgbToOklch.l,
+          c = _rgbToOklch.c,
+          _h = _rgbToOklch.h;
+        return "oklch(".concat(round(_l, 4), " ").concat(round(c, 4), " ").concat(round(_h, 2)).concat(alphaSuffix, ")");
+      }
+  }
+}
+
+/**
+ * Converts a color string to the canonical string of the given format, or
+ * `null` if the input cannot be parsed.
+ */
+function convertColor(value, format) {
+  var parsed = parseColor(value);
+  if (parsed === null) {
+    return null;
+  }
+  return formatColor(parsed, format);
+}
+
+/**
+ * `#rrggbb`, which is what `<input type="color">` uses as its value.
+ */
+function colorToHex(color) {
+  return "#".concat(toHexPair(color.r)).concat(toHexPair(color.g)).concat(toHexPair(color.b));
+}
+
+/**
+ * An example of the canonical output of each format, used in error messages so
+ * that the expected syntax is obvious from the error alone.
+ */
+var FORMAT_EXAMPLES = {
+  hex: "#3b82f6",
+  rgb: "rgb(59 130 246)",
+  hsl: "hsl(217.22 91.22% 59.8%)",
+  oklch: "oklch(0.6231 0.188 259.81)"
+};
+var ColorSchema = /*#__PURE__*/function (_Schema) {
+  function ColorSchema(options) {
+    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;
+    _classCallCheck(this, ColorSchema);
+    _this = _callSuper(this, ColorSchema);
+    _this.options = options;
+    _this.opt = opt;
+    _this.customValidateFunctions = customValidateFunctions;
+    _this.isReadonly = isReadonly;
+    _this.isHidden = isHidden;
+    _this.description = description;
+    return _this;
+  }
+  _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);
+    }
+  }, {
+    key: "validate",
+    value: function validate(validationFunction) {
+      return new ColorSchema(this.options, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.isReadonly, this.isHidden, this.description);
+    }
+  }, {
+    key: "executeCustomValidateAt",
+    value: function executeCustomValidateAt(path, src) {
+      return this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+    }
+  }, {
+    key: "executeValidate",
+    value: function executeValidate(path, src) {
+      var _this$options$format, _this$options;
+      var errors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+      if (this.opt && (src === null || src === undefined)) {
+        return errors.length > 0 ? _defineProperty({}, path, errors) : false;
+      }
+      if (typeof src !== "string") {
+        errors.push({
+          message: "Expected 'string', got '".concat(_typeof(src), "'"),
+          value: src
+        });
+        return _defineProperty({}, path, errors);
+      }
+      var expectedFormat = (_this$options$format = (_this$options = this.options) === null || _this$options === void 0 ? void 0 : _this$options.format) !== null && _this$options$format !== void 0 ? _this$options$format : DEFAULT_COLOR_FORMAT;
+      var parsed = parseColor(src);
+      if (parsed === null) {
+        errors.push({
+          message: "Invalid color: '".concat(src, "'. Expected a CSS color in the '").concat(expectedFormat, "' format (e.g. '").concat(FORMAT_EXAMPLES[expectedFormat], "')"),
+          value: src
+        });
+      } else {
+        var _this$options3;
+        var actualFormat = detectColorFormat(src);
+        if (actualFormat !== expectedFormat) {
+          var _this$options2;
+          // Drop alpha from the SUGGESTION when alpha is not enabled, the same way
+          // the field's commit does. Keeping it would suggest a value that fails
+          // the alpha check immediately below, so following the advice would not
+          // clear the error.
+          var suggestion = formatColor((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.alpha ? parsed : _objectSpread2(_objectSpread2({}, parsed), {}, {
+            a: 1
+          }), expectedFormat);
+          errors.push({
+            message: "Expected a color in the '".concat(expectedFormat, "' format (e.g. '").concat(FORMAT_EXAMPLES[expectedFormat], "'), got '").concat(src, "'. Did you mean '").concat(suggestion, "'?"),
+            value: src
+          });
+        }
+        if (!((_this$options3 = this.options) !== null && _this$options3 !== void 0 && _this$options3.alpha) && parsed.a < 1) {
+          errors.push({
+            message: "Color '".concat(src, "' has an alpha channel, but alpha is not enabled. Use s.color({ alpha: true }) to allow transparency"),
+            value: src
+          });
+        }
+      }
+      if (errors.length > 0) {
+        return _defineProperty({}, path, errors);
+      }
+      return false;
+    }
+  }, {
+    key: "executeAssert",
+    value: function executeAssert(path, src) {
+      if (this.opt && src === null) {
+        return {
+          success: true,
+          data: src
+        };
+      }
+      if (src === null) {
+        return {
+          success: false,
+          errors: _defineProperty({}, path, [{
+            message: "Expected 'string', got 'null'",
+            typeError: true
+          }])
+        };
+      }
+      if (typeof src !== "string") {
+        return {
+          success: false,
+          errors: _defineProperty({}, path, [{
+            message: "Expected 'string', got '".concat(_typeof(src), "'"),
+            typeError: true
+          }])
+        };
+      }
+      return {
+        success: true,
+        data: src
+      };
+    }
+  }, {
+    key: "nullable",
+    value: function nullable() {
+      return new ColorSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description);
+    }
+  }, {
+    key: "readonly",
+    value: function readonly() {
+      return new ColorSchema(this.options, this.opt, this.customValidateFunctions, true, this.isHidden, this.description);
+    }
+  }, {
+    key: "hidden",
+    value: function hidden() {
+      return new ColorSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, true, this.description);
+    }
+  }, {
+    key: "executeSerialize",
+    value: function executeSerialize() {
+      var _this$customValidateF;
+      return {
+        type: "color",
+        opt: this.opt,
+        options: this.options,
+        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: "executeRender",
+    value: function executeRender() {
+      return {};
+    }
+  }]);
+}(Schema);
+var color = function color(options) {
+  return new ColorSchema(options);
+};
+
 function router(router, keyOrItem, maybeItem) {
   if (maybeItem) {
     return new RecordSchema(maybeItem, false, [], router, keyOrItem);
@@ -5476,8 +6160,9 @@ function router(router, keyOrItem, maybeItem) {
 /**
  * Define a collection of images.
  *
- * All options are optional: `s.images()` accepts any image type (`"image/*"`) in
- * the default `/public/val` directory, with nullable alt text and remote disabled.
+ * `directory` is required — it decides where uploads land, so it is not something
+ * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
+ * text, remote disabled.
  *
  * @example
  * ```typescript
@@ -5497,9 +6182,9 @@ function router(router, keyOrItem, maybeItem) {
  * ```
  */
 var images = function images(options) {
-  var _options$directory, _options$alt, _options$accept, _options$remote;
-  var directory = (_options$directory = options === null || options === void 0 ? void 0 : options.directory) !== null && _options$directory !== void 0 ? _options$directory : "/public/val";
-  var altSchema = (_options$alt = options === null || options === void 0 ? void 0 : options.alt) !== null && _options$alt !== void 0 ? _options$alt : string().nullable();
+  var _options$alt, _options$accept, _options$remote;
+  var directory = options.directory;
+  var altSchema = (_options$alt = options.alt) !== null && _options$alt !== void 0 ? _options$alt : string().nullable();
   var itemSchema = new ObjectSchema({
     width: new NumberSchema(undefined, false),
     height: new NumberSchema(undefined, false),
@@ -5508,9 +6193,9 @@ var images = function images(options) {
   }, false);
   return new RecordSchema(itemSchema, false, [], null, null, {
     type: "images",
-    accept: (_options$accept = options === null || options === void 0 ? void 0 : options.accept) !== null && _options$accept !== void 0 ? _options$accept : "image/*",
+    accept: (_options$accept = options.accept) !== null && _options$accept !== void 0 ? _options$accept : "image/*",
     directory: directory,
-    remote: (_options$remote = options === null || options === void 0 ? void 0 : options.remote) !== null && _options$remote !== void 0 ? _options$remote : false,
+    remote: (_options$remote = options.remote) !== null && _options$remote !== void 0 ? _options$remote : false,
     altSchema: altSchema
   });
 };
@@ -5541,6 +6226,7 @@ function initSchema() {
     files: files,
     date: date,
     datetime: datetime,
+    color: color,
     route: route,
     router: router,
     images: images
@@ -6110,7 +6796,7 @@ function collectObjectRecursive(item, collector) {
  * Extracts schemas and sources from a ValModules registry and computes the
  * deterministic SHAs that the server and client both use to detect changes.
  *
- * Used by ValOps on the server and by ValSyncEngine on the client so the
+ * Used by ValOps on the server and by `HostStore` on the client so the
  * hash algorithm has a single source of truth.
  */
 function extractValModules(_x) {
@@ -6286,6 +6972,104 @@ function _extractValModules() {
   return _extractValModules.apply(this, arguments);
 }
 
+/**
+ * Does this schema store any file remotely?
+ *
+ * The one answer to that question. There used to be two — `hasRemoteFileSchema`
+ * in the server, gating whether `/save` demands remote credentials, and
+ * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
+ * and they disagreed about `s.images({ remote: true })`: the Studio's counted a
+ * remote media record, the server's did not, because a media collection
+ * serializes as a `record` of metadata rather than as an image schema.
+ *
+ * The server's answer was the wrong one, and silently so. With it false,
+ * `/save` runs `saveOrUploadFiles` in `skip-remote` mode, and that mode does not
+ * merely skip the upload — it drops every remote descriptor without an error. The
+ * commit then lands a remote ref with no bytes behind it: a broken image, in the
+ * repository, with nothing anywhere saying why.
+ *
+ * ## Why it stays a walk over the SERIALIZED schema
+ *
+ * Both callers have a `SerializedSchema` and not a `Schema`: the server reads
+ * them out of `getSchemas()`, and the Studio is handed them by `host.receive`.
+ * Asking the schema classes directly would mean a method on every one of them,
+ * and the two places that need the answer cannot call it.
+ *
+ * ## Throwing
+ *
+ * The `never` assignment at the end is the point of the default branch: adding a
+ * schema type without teaching this function about it must not compile. The throw
+ * is what happens if one arrives anyway — which for a caller reading schemas out
+ * of its own process should be impossible. A caller that cannot afford to throw
+ * (the Studio, whose whole UI is downstream of this) catches it; returning `false`
+ * instead would reintroduce exactly the silent skip described above.
+ */
+function hasRemoteFileSchema(schema) {
+  if (schema.type === "file" || schema.type === "image") {
+    return !!schema.remote;
+  } else if (schema.type === "richtext") {
+    var _schema$options;
+    if (_typeof((_schema$options = schema.options) === null || _schema$options === void 0 || (_schema$options = _schema$options.inline) === null || _schema$options === void 0 ? void 0 : _schema$options.img) === "object") {
+      return hasRemoteFileSchema(schema.options.inline.img);
+    }
+    return false;
+  } else if (schema.type === "array") {
+    return hasRemoteFileSchema(schema.item);
+  } else if (schema.type === "record") {
+    /**
+     * A media collection — `s.images()` / `s.files()` — is the case both of the
+     * old functions were written around, and the one they disagreed on.
+     *
+     * It has no file or image schema inside it to find: `item` is an object of
+     * width/height/mimeType/alt, and the file itself is named by the record's
+     * KEY. So `remote` on the record is the only place the answer is written
+     * down, and recursing into `item` can only ever say no.
+     */
+    if (schema.mediaType && schema.remote) {
+      return true;
+    }
+    return hasRemoteFileSchema(schema.item);
+  } else if (schema.type === "object") {
+    for (var key in schema.items) {
+      var hasRemoteFile = hasRemoteFileSchema(schema.items[key]);
+      if (hasRemoteFile) {
+        return true;
+      }
+    }
+    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;
+          }
+        }
+      } 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 === "keyOf" || schema.type === "route") {
+    return false;
+  } else {
+    var exhaustiveCheck = schema;
+    throw new Error("Unexpected schema: ".concat(JSON.stringify(exhaustiveCheck)));
+  }
+}
+
 var DEFAULT_VAL_REMOTE_HOST = "https://remote.val.build";
 function convertRemoteSource(src) {
   if (src !== null && src !== void 0 && src.patch_id) {
@@ -7263,6 +8047,8 @@ function deserializeSchemaImpl(serialized) {
       return new DateSchema(serialized.options, serialized.opt, [], false, false, serialized.description);
     case "dateTime":
       return new DateTimeSchema(serialized.options, serialized.opt, [], false, false, serialized.description);
+    case "color":
+      return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description);
     default:
       {
         var exhaustiveCheck = serialized;
@@ -7276,6 +8062,94 @@ function deserializeSchemaImpl(serialized) {
   }
 }
 
+// TODO: we want to change layout -> as to be more consistent across the board
+
+// Main render type:
+
+//
+
+/**
+ * Which paths a render is being computed FOR.
+ *
+ * `executeRender` takes a whole module, so one request has always walked every
+ * node in it and run every `select` closure — for `handboka`, with `select` at
+ * two nested array levels, that is every chapter and every section to serve one
+ * visible row. A scope is what makes the walk proportional to what is being
+ * looked at instead of to the project.
+ *
+ * Two questions, because a container and its items need different answers:
+ *
+ * - {@link RenderScope.wants} — is a render AT this exact path wanted? A
+ *   container answers `true` here when the whole of it is being shown, and its
+ *   list render is then computed in full.
+ * - {@link RenderScope.wantsUnder} — could anything at or below this path be
+ *   wanted? Recursion is pruned where this is `false`, and a container whose own
+ *   path is not wanted but which has wanted descendants renders a WINDOW: only
+ *   the items that were asked for. That is the case a single visible row is, and
+ *   it is why {@link ListArrayRender} carries indices.
+ *
+ * Absent scope means the whole module, which is what every existing caller
+ * passes and what every existing caller got.
+ */
+
+/**
+ * A scope covering exactly `paths` and their subtrees.
+ *
+ * Compares SEGMENTS rather than string prefixes. A source path's module path is
+ * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
+ * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
+ * dot or a quote — `"title"` against `"titles"` being the cheapest example.
+ * Segments are parsed once here, not per comparison.
+ */
+function renderScope(paths) {
+  var wanted = paths.map(function (path) {
+    var _splitModuleFilePathA = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA2 = _slicedToArray(_splitModuleFilePathA, 2),
+      moduleFilePath = _splitModuleFilePathA2[0],
+      modulePath = _splitModuleFilePathA2[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  });
+  var parse = function parse(path) {
+    var _splitModuleFilePathA3 = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA4 = _slicedToArray(_splitModuleFilePathA3, 2),
+      moduleFilePath = _splitModuleFilePathA4[0],
+      modulePath = _splitModuleFilePathA4[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  };
+  var isPrefix = function isPrefix(prefix, of) {
+    if (prefix.length > of.length) return false;
+    for (var i = 0; i < prefix.length; i++) {
+      if (prefix[i] !== of[i]) return false;
+    }
+    return true;
+  };
+  return {
+    wants: function wants(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && entry.segments.length === at.segments.length && isPrefix(entry.segments, at.segments);
+      });
+    },
+    wantsUnder: function wantsUnder(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && (
+        // Either direction: a wanted path below `path` means recurse into it,
+        // and a wanted path ABOVE it means the whole subtree was asked for.
+        isPrefix(at.segments, entry.segments) || isPrefix(entry.segments, at.segments));
+      });
+    }
+  };
+}
+
+// TODO: improve this so that we do not get RawString and string, only string. Are there other things?
+
 var externalPageRouter = {
   getRouterId: function getRouterId() {
     return "external-url-router";
@@ -7549,6 +8423,13 @@ var Internal = {
   joinModuleFilePathAndModulePath: joinModuleFilePathAndModulePath,
   nextAppRouter: nextAppRouter,
   externalPageRouter: externalPageRouter,
+  color: {
+    parseColor: parseColor,
+    formatColor: formatColor,
+    convertColor: convertColor,
+    detectColorFormat: detectColorFormat,
+    colorToHex: colorToHex
+  },
   remote: {
     createRemoteRef: createRemoteRef,
     getValidationBasis: getValidationBasis,
@@ -7629,4 +8510,4 @@ function tryJsonParse(str) {
   }
 }
 
-export { ArraySchema as A, BooleanSchema as B, DEFAULT_CONTENT_HOST as D, FATAL_ERROR_TYPES as F, GenericSelector as G, Internal as I, KeyOfSchema as K, LiteralSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RecordSchema as R, Schema as S, UnionSchema as U, VAL_EXTENSION as V, _typeof as _, _slicedToArray as a, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, DEFAULT_VAL_REMOTE_HOST as g, FILE_REF_PROP as h, initVal as i, FILE_REF_SUBTYPE_TAG as j, derefPatch as k, StringSchema as l, modules as m, ImageSchema as n, FileSchema as o, DateSchema as p, DateTimeSchema as q, RouteSchema as r, splitModuleFilePathAndModulePath as s, RichTextSchema as t, deserializeSchema as u, getSourcePathFromRoute as v };
+export { ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, FATAL_ERROR_TYPES as F, GenericSelector as G, Internal as I, KeyOfSchema as K, LiteralSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RecordSchema as R, Schema as S, UnionSchema as U, VAL_EXTENSION as V, _typeof as _, _slicedToArray as a, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, DEFAULT_VAL_REMOTE_HOST as g, hasRemoteFileSchema as h, initVal as i, FILE_REF_PROP as j, FILE_REF_SUBTYPE_TAG as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, COLOR_FORMATS as r, splitModuleFilePathAndModulePath as s, DEFAULT_COLOR_FORMAT as t, DateTimeSchema as u, RouteSchema as v, RichTextSchema as w, deserializeSchema as x, renderScope as y, getSourcePathFromRoute as z };