@valbuild/core 0.100.0 → 0.102.0

package/dist/{index-92ba715b.cjs.prod.js → index-ca1bbeb2.cjs.prod.js}

@@ -922,6 +922,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,
@@ -947,7 +948,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, {
@@ -1160,7 +1166,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;
@@ -1171,7 +1177,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];
@@ -1313,6 +1325,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,
@@ -1321,7 +1334,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;
@@ -1333,7 +1346,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];
@@ -1349,34 +1365,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;
     }
@@ -1950,7 +1983,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;
@@ -1972,7 +2005,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];
@@ -3859,6 +3892,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,
@@ -3891,7 +3925,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;
@@ -3909,7 +3943,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];
@@ -3925,6 +3962,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),
@@ -3933,6 +3973,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 {
@@ -5065,8 +5108,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);
@@ -5454,6 +5497,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);
@@ -5478,8 +6162,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
@@ -5499,9 +6184,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),
@@ -5510,9 +6195,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
   });
 };
@@ -5543,6 +6228,7 @@ function initSchema() {
     files: files,
     date: date,
     datetime: datetime,
+    color: color,
     route: route,
     router: router,
     images: images
@@ -6112,7 +6798,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) {
@@ -6288,6 +6974,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 = result._createForOfIteratorHelper(unionObjectSchema.items),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var item = _step.value;
+          var _hasRemoteFile = hasRemoteFileSchema(item);
+          if (_hasRemoteFile) {
+            return true;
+          }
+        }
+      } 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) {
@@ -7265,6 +8049,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;
@@ -7278,6 +8064,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";
@@ -7551,6 +8425,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,
@@ -7633,7 +8514,10 @@ function tryJsonParse(str) {
 
 exports.ArraySchema = ArraySchema;
 exports.BooleanSchema = BooleanSchema;
+exports.COLOR_FORMATS = COLOR_FORMATS;
+exports.ColorSchema = ColorSchema;
 exports.DEFAULT_APP_HOST = DEFAULT_APP_HOST;
+exports.DEFAULT_COLOR_FORMAT = DEFAULT_COLOR_FORMAT;
 exports.DEFAULT_CONTENT_HOST = DEFAULT_CONTENT_HOST;
 exports.DEFAULT_VAL_REMOTE_HOST = DEFAULT_VAL_REMOTE_HOST;
 exports.DateSchema = DateSchema;
@@ -7667,6 +8551,8 @@ exports.derefPatch = derefPatch;
 exports.deserializeSchema = deserializeSchema;
 exports.extractValModules = extractValModules;
 exports.getSourcePathFromRoute = getSourcePathFromRoute;
+exports.hasRemoteFileSchema = hasRemoteFileSchema;
 exports.initVal = initVal;
 exports.modules = modules;
+exports.renderScope = renderScope;
 exports.splitModuleFilePathAndModulePath = splitModuleFilePathAndModulePath;