@valbuild/shared 0.127.0 → 0.129.0

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1,6 +1,6 @@
 import { Internal, CODE_LANGUAGES, resolveSettingsModule, missingDeclaredKeys, localeOfValue, discriminatedUnionBranchOf, DEFAULT_COLOR_FORMAT, declaredKeySetOf } from '@valbuild/core';
-import { _ as _createForOfIteratorHelper, n as _objectSpread2, o as _arrayLikeToArray, q as _unsupportedIterableToArray, r as _defineProperty, s as _typeof } from '../../dist/getSitemapTree-a6cb37cb.esm.js';
-export { b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, g as getNextAppRouterSourceFolder, l as getPageRouterSitemapTree, j as getPageRouterSourceFolder, m as getPatternFromModuleFilePath, h as getTanStackRouterSourceFolder, k as isTanStackRoutesFolder, f as isValCanvasFrame, i as isValCanvasPageMessage, e as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-a6cb37cb.esm.js';
+import { _ as _createForOfIteratorHelper, o as _objectSpread2, q as _arrayLikeToArray, r as _unsupportedIterableToArray, s as _typeof, t as _defineProperty } from '../../dist/getSitemapTree-878d3888.esm.js';
+export { D as DEFAULT_CANVAS_SELECTION, e as DEFAULT_CANVAS_SELECTION_SOFT, b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, h as getNextAppRouterSourceFolder, m as getPageRouterSitemapTree, k as getPageRouterSourceFolder, n as getPatternFromModuleFilePath, j as getTanStackRouterSourceFolder, l as isTanStackRoutesFolder, g as isValCanvasFrame, i as isValCanvasPageMessage, f as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-878d3888.esm.js';
 import { z } from 'zod';
 import { fromError } from 'zod-validation-error';
 import FlexSearch from 'flexsearch';
@@ -890,10 +890,34 @@ var PatchBlock = z.object({
   parentRef: ParentRef$1
 });
 
+function _objectWithoutPropertiesLoose(r, e) {
+  if (null == r) return {};
+  var t = {};
+  for (var n in r) if ({}.hasOwnProperty.call(r, n)) {
+    if (-1 !== e.indexOf(n)) continue;
+    t[n] = r[n];
+  }
+  return t;
+}
+
+function _objectWithoutProperties(e, t) {
+  if (null == e) return {};
+  var o,
+    r,
+    i = _objectWithoutPropertiesLoose(e, t);
+  if (Object.getOwnPropertySymbols) {
+    var n = Object.getOwnPropertySymbols(e);
+    for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]);
+  }
+  return i;
+}
+
 var SourcePath = z.string().transform(function (path) {
   return path;
 });
 
+var _excluded = ["directory"];
+
 // A render is static config, so unlike a `preview` it travels WHOLE — this
 // is the field the editor reads the layout from. See `core/src/render.ts`.
 // Every field can carry `{ as: "inline" }`, and that is all a render says.
@@ -1001,11 +1025,35 @@ var ImageEncodeOption = z.union([z.literal(false), z.object({
   maxWidth: z.number().optional(),
   maxHeight: z.number().optional()
 })]);
-var ImageOptions = z.object({
-  directory: z.string().optional(),
+/**
+ * Accept the pre-rename `directory` key and read it as `dir`.
+ *
+ * Serialized schemas are not only computed from live code: a commit record
+ * stores the schema each module was under (`StoredModuleVersion`), and the
+ * history view parses those back. Commits made before `directory` became `dir`
+ * therefore still carry the old key, and dropping it would show a historical
+ * gallery with no directory at all — silently, since the rest of the schema
+ * parses fine.
+ *
+ * Only fills `dir` when it is absent, so a schema carrying both (which should
+ * not happen) keeps the current key.
+ */
+var readLegacyDirectoryAsDir = function readLegacyDirectoryAsDir(value) {
+  if (!value || _typeof(value) !== "object" || Array.isArray(value) || !("directory" in value) || "dir" in value) {
+    return value;
+  }
+  var _ref = value,
+    directory = _ref.directory,
+    rest = _objectWithoutProperties(_ref, _excluded);
+  return _objectSpread2(_objectSpread2({}, rest), {}, {
+    dir: directory
+  });
+};
+var ImageOptions = z.preprocess(readLegacyDirectoryAsDir, z.object({
+  dir: z.string().optional(),
   accept: z.string().optional(),
   encode: ImageEncodeOption.optional()
-});
+}));
 var SerializedImageSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("image"),
   options: ImageOptions.optional(),
@@ -1044,7 +1092,7 @@ var SerializedRichTextSchema = z.object(_objectSpread2(_objectSpread2({}, common
   opt: z["boolean"]()
 }));
 var SerializedRecordSchema = z.lazy(function () {
-  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+  return z.preprocess(readLegacyDirectoryAsDir, z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("record"),
     item: SerializedSchema,
     opt: z["boolean"](),
@@ -1052,12 +1100,12 @@ var SerializedRecordSchema = z.lazy(function () {
     mediaType: z.union([z.literal("files"), z.literal("images")]).optional(),
     // Optional legacy gallery metadata
     accept: z.string().optional(),
-    directory: z.string().optional(),
+    dir: z.string().optional(),
     remote: z["boolean"]().optional(),
     encode: ImageEncodeOption.optional(),
     alt: SerializedSchema.optional(),
     moduleMetadata: z.record(z.string(), z.record(z.string(), z.any())).optional()
-  })).passthrough();
+  })).passthrough());
 });
 var SerializedKeyOfSchema = z.lazy(function () {
   return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
@@ -4697,7 +4745,7 @@ function getSourceAt(source, path) {
  * Walks `schema` along `path`, returning a structured result:
  * - `leaf`: walked the full path; resolved schema at the end.
  * - `richtext`: hit a richtext mid-walk; richtext is the resolved schema.
- * - `gallery-traversed`: hit an `s.images()` record and walked past it (i.e. the
+ * - `gallery-traversed`: hit an `s.imageset()` record and walked past it (i.e. the
  *   path tries to address an entry inside the gallery — a clue the AI should
  *   have used the gallery tool instead).
  * - `unresolved`: the path could not be walked.
@@ -4828,7 +4876,7 @@ function buildImageGalleryPatch(args, moduleSchema) {
     op: "add",
     path: [args.filePath],
     value: _objectSpread2(_objectSpread2({}, args.metadata), {}, {
-      // `alt` is a REQUIRED field of a gallery entry (`s.images()` gives it a
+      // `alt` is a REQUIRED field of a gallery entry (`s.imageset()` gives it a
       // nullable string schema), so an entry written without one is invalid
       // the moment it lands — and the caller that had no alt to give is the
       // common case, not the odd one. Null is what the Studio's own upload
@@ -4891,10 +4939,10 @@ function buildRemoveImageGalleryEntryPatch(args, moduleSchema, moduleSource) {
 var GALLERY_REDIRECT = {
   kind: "wrong-tool",
   suggestedTool: "add_session_image_to_gallery",
-  reason: "Destination is a media gallery (s.images() / s.files()). Gallery entries are keyed by file path and carry a file on disk, so they cannot be created with a plain patch. Use add_session_image_to_gallery."
+  reason: "Destination is a media gallery (s.imageset() / s.fileset()). Gallery entries are keyed by file path and carry a file on disk, so they cannot be created with a plain patch. Use add_session_image_to_gallery."
 };
 
-/** An `s.images()` / `s.files()` record: a gallery, not an ordinary record. */
+/** An `s.imageset()` / `s.fileset()` record: a gallery, not an ordinary record. */
 function isGallery(schema) {
   return schema.type === "record" && schema.mediaType !== undefined;
 }
@@ -6064,4 +6112,497 @@ function performSearch(searchIndex, query) {
   };
 }
 
-export { Api, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, ValCommit, ValDeployment, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, checkCompatibility, chooseEncoded, concatModulePath, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, newestCommitSha, partitionValidationErrors, performSearch, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+/**
+ * The Studio's chrome, generated from one colour.
+ *
+ * `s.settings()`'s `theme.accent` is a single hex, and what it has to replace is
+ * a TEN-STEP RAMP: `index.css` declares `--colors-brand-green-100` through
+ * `-1000` and every brand token points into it, picking different steps in light
+ * and in dark (a tinted surface is step 200 in light and 800 in dark; the text
+ * on it is 1000 and 100). So the accent is not a colour to place, it is a ramp
+ * to build — which is also why one accent drives both modes with nothing to keep
+ * in sync.
+ *
+ * ## Why an arbitrary hex is safe
+ *
+ * The obvious worry is `contrast.test.ts`, which holds every foreground /
+ * background pair the chrome renders to WCAG AA. A hex typed by an editor never
+ * goes near that test.
+ *
+ * It holds anyway, because of how the ramp is built: **green's lightness at each
+ * step is reused unchanged, and only the hue moves.** WCAG relative luminance is
+ * almost entirely a function of lightness, so a ramp that keeps green's L
+ * profile keeps green's contrast relationships. Chroma is scaled to the accent's
+ * own saturation and then reduced — never L — until each step fits sRGB.
+ *
+ * "Almost entirely" is doing real work in that sentence: at equal OKLCH
+ * lightness a saturated yellow has a higher relative luminance than a blue, so
+ * the ratios do move a little. {@link BRAND_CONTRAST_PAIRS} is the list of pairs
+ * that have to survive it, and `accentRamp.test.ts` runs them over the hue
+ * circle rather than trusting the argument.
+ *
+ * ## What is NOT generated
+ *
+ * With no accent set, the hand-tuned ramp in `index.css` is used as it is. This
+ * module reproduces it to within a step or two, and re-deriving a value somebody
+ * tuned by eye is a silent regression rather than a simplification.
+ */
+
+/** The steps `index.css` declares, smallest (lightest) first. */
+var RAMP_STEPS = [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000];
+/**
+ * Val's own brand ramp, and the lightness profile every generated ramp borrows.
+ *
+ * A copy of what `index.css` declares, because this package cannot read the UI
+ * package's stylesheet — so the two are held together by a test instead:
+ * `contrast.test.ts` resolves the ramp out of the real CSS and asserts it equals
+ * this. If that test fails, the stylesheet moved and this did not.
+ */
+var VAL_GREEN_RAMP = {
+  100: "#dcfae6",
+  200: "#abefc6",
+  300: "#75e0a7",
+  400: "#47cd89",
+  500: "#17b26a",
+  600: "#079455",
+  700: "#067647",
+  800: "#085d3a",
+  900: "#074d31",
+  1000: "#053321"
+};
+
+/**
+ * The step the accent itself becomes, and therefore the step the whole ramp's
+ * chroma is scaled against.
+ *
+ * 500 rather than 600: it is the most saturated step in the green ramp, so an
+ * accent anchored there is reproduced about as faithfully as the ramp allows,
+ * and the steps either side of it stay in the same relationship to it that
+ * green's do.
+ */
+var ANCHOR_STEP = 500;
+
+/**
+ * The step drawn on the CUSTOMER's page, as an outline around every editable
+ * element.
+ *
+ * 600 is the step `index.css` pins the page-selection tokens to, for a reason
+ * worth keeping: it clears 3:1 against both white and black, so the outlines
+ * stay visible whatever the site behind them looks like. A generated ramp
+ * inherits that because it inherits green-600's lightness — and
+ * `accentRamp.test.ts` checks it on both grounds rather than assuming.
+ */
+var PAGE_SELECTION_STEP = 600;
+
+// ---------------------------------------------------------------------------
+// sRGB <-> OKLCH
+//
+// Written out rather than taken from a dependency: it is thirty lines, it runs
+// on every Studio render that has an accent, and `s.color()` already carries
+// its own copy of the neighbouring maths (`schema/colorFormat.ts`) for the same
+// reason.
+// ---------------------------------------------------------------------------
+
+/** OKLCH: lightness 0-1, chroma, hue in degrees. */
+
+/**
+ * Every hex form `s.color({ format: "hex" })` accepts.
+ *
+ * Three and four digits as well as six and eight, because that is what the
+ * schema validates — `detectColorFormat` calls anything starting with `#` hex,
+ * and `#fff` parses. A generator that took only six digits left a
+ * schema-VALID accent doing nothing at all: no ramp, no error, and a Studio
+ * still on Val green with a colour sitting in the settings module.
+ */
+var HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function linearToSrgb(c) {
+  return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+/**
+ * `null` for anything that is not a hex colour.
+ *
+ * Alpha is read and discarded. The ramp is a set of opaque surfaces and text
+ * colours, and `s.color()` rejects a non-opaque value anyway unless the field
+ * enabled alpha — which `theme.accent` does not. So `#0f08` is the same accent
+ * as `#0f0`, rather than nothing at all.
+ */
+function hexToRgb(hex) {
+  var trimmed = hex.trim();
+  if (!HEX.test(trimmed)) {
+    return null;
+  }
+  var digits = trimmed.slice(1);
+  var _short = digits.length <= 4;
+  var channel = function channel(index) {
+    var slice = _short ? digits[index].repeat(2) : digits.slice(index * 2, index * 2 + 2);
+    return parseInt(slice, 16) / 255;
+  };
+  return [channel(0), channel(1), channel(2)];
+}
+function rgbToHex(rgb) {
+  return "#" + rgb.map(function (c) {
+    return Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, "0");
+  }).join("");
+}
+function rgbToOklch(rgb) {
+  var r = srgbToLinear(rgb[0]);
+  var g = srgbToLinear(rgb[1]);
+  var b = srgbToLinear(rgb[2]);
+  var l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  var m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  var s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  var okL = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  var okA = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  var okB = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return [okL, Math.hypot(okA, okB), Math.atan2(okB, okA) * 180 / Math.PI];
+}
+function oklchToRgb(lch) {
+  var okA = lch[1] * Math.cos(lch[2] * Math.PI / 180);
+  var okB = lch[1] * Math.sin(lch[2] * Math.PI / 180);
+  var l = Math.pow(lch[0] + 0.3963377774 * okA + 0.2158037573 * okB, 3);
+  var m = Math.pow(lch[0] - 0.1055613458 * okA - 0.0638541728 * okB, 3);
+  var s = Math.pow(lch[0] - 0.0894841775 * okA - 1.291485548 * okB, 3);
+  return [linearToSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), linearToSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), linearToSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)];
+}
+
+/** A hair of slack, so a colour that is exactly at the edge is not clamped. */
+var GAMUT_EPSILON = 0.0005;
+function inGamut(rgb) {
+  return rgb.every(function (c) {
+    return c >= -GAMUT_EPSILON && c <= 1 + GAMUT_EPSILON;
+  });
+}
+
+/**
+ * Bring a colour inside sRGB by reducing its CHROMA, never its lightness.
+ *
+ * That restriction is the whole reason the contrast argument holds: clipping
+ * RGB channels (which is what naive conversion does) moves lightness, and a
+ * step that has drifted lighter is a step whose contrast guarantee is gone.
+ * Twenty-four bisections is well past single-byte precision.
+ */
+function clampChromaToGamut(lch) {
+  if (inGamut(oklchToRgb(lch))) {
+    return lch;
+  }
+  var lo = 0;
+  var hi = lch[1];
+  for (var i = 0; i < 24; i++) {
+    var mid = (lo + hi) / 2;
+    if (inGamut(oklchToRgb([lch[0], mid, lch[2]]))) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return [lch[0], lo, lch[2]];
+}
+var GREEN_PROFILE = RAMP_STEPS.map(function (step) {
+  var rgb = hexToRgb(VAL_GREEN_RAMP[step]);
+  if (rgb === null) {
+    // Unreachable: the ramp above is literal hex. Thrown rather than defaulted
+    // because a broken profile would produce a plausible-looking wrong ramp.
+    throw new Error("Val's green ramp holds a non-hex value at step ".concat(step));
+  }
+  return {
+    step: step,
+    lch: rgbToOklch(rgb)
+  };
+});
+
+/**
+ * The ten-step ramp for one accent, or `null` if it is not a six-digit hex.
+ *
+ * `null` rather than a fallback: the caller knows whether it is holding a value
+ * an editor picked (in which case the schema already validated it) or one that
+ * came out of a hand-edited settings file, and only the caller can decide
+ * whether "ignore it" or "report it" is right.
+ */
+function accentRamp(accent) {
+  var rgb = hexToRgb(accent);
+  if (rgb === null) {
+    return null;
+  }
+  var _rgbToOklch = rgbToOklch(rgb),
+    _rgbToOklch2 = _slicedToArray(_rgbToOklch, 3),
+    accentChroma = _rgbToOklch2[1],
+    accentHue = _rgbToOklch2[2];
+  var anchor = GREEN_PROFILE.find(function (entry) {
+    return entry.step === ANCHOR_STEP;
+  });
+  if (anchor === undefined || anchor.lch[1] === 0) {
+    throw new Error("Val's green ramp has no chroma at its anchor step");
+  }
+  var chromaScale = accentChroma / anchor.lch[1];
+  var at = function at(step) {
+    var entry = GREEN_PROFILE.find(function (candidate) {
+      return candidate.step === step;
+    });
+    if (entry === undefined) {
+      throw new Error("Val's green ramp has no step ".concat(step));
+    }
+    // Green's lightness and chroma, the accent's hue. Green's own hue is the
+    // one thing a generated ramp does not keep.
+    var _entry$lch = _slicedToArray(entry.lch, 2),
+      lightness = _entry$lch[0],
+      chroma = _entry$lch[1];
+    return rgbToHex(oklchToRgb(clampChromaToGamut([lightness, chroma * chromaScale, accentHue])));
+  };
+  // Written out rather than reduced into, so the type says every step is
+  // present instead of a cast saying so.
+  return {
+    100: at(100),
+    200: at(200),
+    300: at(300),
+    400: at(400),
+    500: at(500),
+    600: at(600),
+    700: at(700),
+    800: at(800),
+    900: at(900),
+    1000: at(1000)
+  };
+}
+
+/**
+ * The custom properties that restyle the chrome, ready to put on a `style`
+ * attribute.
+ *
+ * Custom properties on the element rather than a generated stylesheet: nothing
+ * has to be escaped, an inline custom property beats `@layer base` without a
+ * specificity fight, and a subtree that should keep the untouched palette
+ * simply is not given the object. See `useValThemeStyle` for where they go —
+ * every place the Studio stamps `data-mode`, because the theme travels with it.
+ *
+ * Empty when nothing is set, which is what makes "no theme" cost nothing.
+ */
+function themeCustomProperties(theme) {
+  var properties = {};
+  if (theme.accent) {
+    var ramp = accentRamp(theme.accent);
+    if (ramp !== null) {
+      var _iterator = _createForOfIteratorHelper(RAMP_STEPS),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var step = _step.value;
+          properties["--colors-brand-green-".concat(step)] = ramp[step];
+        }
+        /*
+         * The page-selection trio, written OUT rather than left to follow the
+         * ramp — and the first of them is the one that has to be said out loud,
+         * because it looks like it should follow and does not.
+         *
+         * `index.css` declares `--bg-page-selection: var(--colors-brand-green-600)`,
+         * so overriding the ramp looks like enough. It is not: **a `var()` inside
+         * a custom property is substituted where the property is DECLARED, not
+         * where it is used.** That declaration lives in the light block, whose
+         * selector is `:host, :root, *[data-mode="light"]` — so on a
+         * `data-mode="dark"` element the rule does not match, nothing is declared
+         * there, and what the element inherits from `:host` is the value already
+         * substituted to green. An override of the ramp on the element cannot
+         * reach backwards into it.
+         *
+         * The brand tokens escape this only because the DARK block re-declares
+         * them: `--bg-brand-primary: var(--colors-brand-green-800)` is computed
+         * on the themed element itself, so it resolves against the override. The
+         * page-selection tokens are deliberately declared once and never flipped
+         * with the theme (the page underneath is not a Val surface), which is
+         * exactly what puts them outside that mechanism.
+         *
+         * So: anything that depends on the ramp and is not re-declared per mode
+         * has to be written here. `brandDerivedTokens.test.ts` scans the
+         * stylesheet and fails if another one appears.
+         */
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      properties["--bg-page-selection"] = ramp[PAGE_SELECTION_STEP];
+      var selection = hexToRgb(ramp[PAGE_SELECTION_STEP]);
+      if (selection !== null) {
+        var channels = selection.map(function (c) {
+          return Math.round(c * 255);
+        }).join(", ");
+        properties["--bg-page-selection-fill"] = "rgba(".concat(channels, ", 0.12)");
+        properties["--bg-page-selection-soft"] = "rgba(".concat(channels, ", 0.4)");
+      }
+    }
+  }
+  if (theme.radius) {
+    properties["--radius"] = theme.radius;
+  }
+  return properties;
+}
+
+/**
+ * WCAG relative luminance of a six-digit hex.
+ *
+ * Exported so there is one implementation of the maths that decides whether a
+ * theme is legible; `contrast.test.ts` had its own copy, and two copies of a
+ * threshold is how a guarantee quietly stops being one.
+ */
+function relativeLuminance(hex) {
+  var rgb = hexToRgb(hex);
+  if (rgb === null) {
+    throw new Error("Not a six-digit hex colour: ".concat(hex));
+  }
+  var _rgb$map = rgb.map(srgbToLinear),
+    _rgb$map2 = _slicedToArray(_rgb$map, 3),
+    r = _rgb$map2[0],
+    g = _rgb$map2[1],
+    b = _rgb$map2[2];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio between two six-digit hex colours, 1 to 21. */
+function contrastRatio(a, b) {
+  var la = relativeLuminance(a);
+  var lb = relativeLuminance(b);
+  var hi = Math.max(la, lb);
+  var lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** WCAG AA for body text. */
+var AA_TEXT = 4.5;
+/** WCAG AA for large text and for UI components such as a focus ring. */
+var AA_LARGE = 3;
+
+/**
+ * Where a brand pair's background comes from.
+ *
+ * A `RampStep` is a step of the brand ramp, so it moves with the accent. A hex
+ * is a neutral surface that does not — the canvas and the floating panels are
+ * grey in every theme, and a ring has to be legible against them.
+ */
+
+/**
+ * Every foreground / background pair the chrome renders with BRAND colours.
+ *
+ * The list is data rather than a test body because two different things have to
+ * be held to it, and one table is the only way they can agree:
+ *
+ * - `accentRamp.test.ts` runs it over ramps generated across the hue circle,
+ *   which is what makes an arbitrary accent safe.
+ * - `contrast.test.ts` runs it over the ramp resolved out of the real
+ *   `index.css`, which is what stops someone nudging Val's own green past AA.
+ *
+ * The neutral pairs — muted text on a panel, a hairline on the canvas — stay in
+ * `contrast.test.ts`. They have nothing to do with the accent, and a theme
+ * cannot move them.
+ */
+var BRAND_CONTRAST_PAIRS = [
+// Light: `--bg-brand-primary` is step 200, with `--fg-brand-primary` (1000)
+// and `--fg-brand-primary-alt` (900) on it.
+{
+  what: "fg-brand-primary on bg-brand-primary",
+  mode: "light",
+  fg: 1000,
+  bg: 200,
+  min: AA_TEXT
+}, {
+  what: "fg-brand-primary-alt on bg-brand-primary",
+  mode: "light",
+  fg: 900,
+  bg: 200,
+  min: AA_TEXT
+},
+// Light: `--bg-brand-secondary` is the filled step 800.
+{
+  what: "fg-brand-secondary on bg-brand-secondary",
+  mode: "light",
+  fg: 100,
+  bg: 800,
+  min: AA_TEXT
+}, {
+  what: "fg-brand-secondary-alt on bg-brand-secondary",
+  mode: "light",
+  fg: 200,
+  bg: 800,
+  min: AA_TEXT
+},
+// Light: `--border-focus` is step 600, and it has to read on both neutral
+// surfaces a focused control can sit on.
+{
+  what: "border-focus on bg-float",
+  mode: "light",
+  fg: 600,
+  bg: "#fcfcfc",
+  min: AA_LARGE
+}, {
+  what: "border-focus on bg-canvas",
+  mode: "light",
+  fg: 600,
+  bg: "#f4f4f5",
+  min: AA_LARGE
+},
+// The outlines drawn on the customer's own page. Not a Val surface at all,
+// which is why the grounds are pure white and pure black: the site behind
+// them can be anything.
+{
+  what: "bg-page-selection on a white site",
+  mode: "light",
+  fg: 600,
+  bg: "#ffffff",
+  min: AA_LARGE
+}, {
+  what: "bg-page-selection on a black site",
+  mode: "light",
+  fg: 600,
+  bg: "#000000",
+  min: AA_LARGE
+},
+// Dark inverts which step is the surface and which is the text.
+{
+  what: "fg-brand-primary on bg-brand-primary",
+  mode: "dark",
+  fg: 100,
+  bg: 800,
+  min: AA_TEXT
+}, {
+  what: "fg-brand-primary-alt on bg-brand-primary",
+  mode: "dark",
+  fg: 200,
+  bg: 800,
+  min: AA_TEXT
+}, {
+  what: "fg-brand-secondary on bg-brand-secondary",
+  mode: "dark",
+  fg: 1000,
+  bg: 200,
+  min: AA_TEXT
+}, {
+  what: "fg-brand-secondary-alt on bg-brand-secondary",
+  mode: "dark",
+  fg: 900,
+  bg: 200,
+  min: AA_TEXT
+},
+// Dark's focus ring lightens rather than mirroring: step 600 is nearly
+// invisible against the dark canvas.
+{
+  what: "border-focus on bg-canvas",
+  mode: "dark",
+  fg: 400,
+  bg: "#08080a",
+  min: AA_LARGE
+}, {
+  what: "border-focus on bg-float",
+  mode: "dark",
+  fg: 400,
+  bg: "#131316",
+  min: AA_LARGE
+}];
+
+/** Resolve one side of a {@link BRAND_CONTRAST_PAIRS} entry against a ramp. */
+function resolvePairGround(ground, ramp) {
+  return typeof ground === "number" ? ramp[ground] : ground;
+}
+
+export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, ValCommit, ValDeployment, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, newestCommitSha, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.127.0",
+  "version": "0.129.0",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -37,7 +37,7 @@
     "flexsearch": "^0.8.212",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.127.0"
+    "@valbuild/core": "0.129.0"
   },
   "files": [
     "CHANGELOG.md",