@valbuild/shared 0.125.0 → 0.127.0

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

@@ -1,4 +1,4 @@
-import { Internal, CODE_LANGUAGES, DEFAULT_COLOR_FORMAT } from '@valbuild/core';
+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 { z } from 'zod';
@@ -982,19 +982,19 @@ var SerializedArraySchema = z.lazy(function () {
     opt: z["boolean"]()
   }));
 });
-var SerializedUnionSchema = z.lazy(function () {
-  return z.union([z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
-    type: z.literal("union"),
-    key: SerializedLiteralSchema,
-    items: z.array(SerializedLiteralSchema),
-    opt: z["boolean"]()
-  })), z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
-    type: z.literal("union"),
+var SerializedDiscriminatedUnionSchema = z.lazy(function () {
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+    type: z.literal("discriminated-union"),
     key: z.string(),
     items: z.array(SerializedObjectSchema),
     opt: z["boolean"]()
-  }))]);
+  }));
 });
+var SerializedEnumSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+  type: z.literal("enum"),
+  values: z.array(z.string()),
+  opt: z["boolean"]()
+}));
 var ImageEncodeOption = z.union([z.literal(false), z.object({
   type: z.literal("webp"),
   quality: z.number().optional(),
@@ -1118,6 +1118,16 @@ var SerializedCodeSchema = z.object(_objectSpread2(_objectSpread2({}, commonSche
   options: CodeOptions.optional(),
   opt: z["boolean"]()
 }));
+var SerializedLocaleSchema = z.object({
+  type: z.literal("locale"),
+  render: FieldRender,
+  preview: z.literal(true).optional(),
+  opt: z["boolean"](),
+  customValidate: z["boolean"]().optional(),
+  readonly: z["boolean"]().optional(),
+  hidden: z["boolean"]().optional(),
+  description: z.string().optional()
+});
 var SerializedRouteSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("route"),
   options: z.object({
@@ -1143,10 +1153,15 @@ var SerializedSettingsSchema = z.lazy(function () {
   return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("settings"),
     items: z.record(z.string(), SerializedSchema),
-    opt: z["boolean"]()
+    opt: z["boolean"](),
+    // Which section this is, where Val has rules about it beyond its keys.
+    // Dropping it would leave the Studio's validation worker running every
+    // field's own rules and none of the cross-field ones — see
+    // `sectionValidators` in core/src/schema/settings.ts.
+    section: z.string().optional()
   }));
 });
-var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
+var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedLocaleSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
 var ValCommit = z.object({
   commitSha: z.string(),
@@ -1158,6 +1173,31 @@ var ValCommit = z.object({
   commitMessage: z.string().nullable()
 });
 
+var ValDeployment = z.object({
+  deploymentId: z.string(),
+  deploymentState: z.string(),
+  commitSha: z.string(),
+  updatedAt: z.string(),
+  createdAt: z.string(),
+  /**
+   * The commit message, as the deployment's host reported it.
+   *
+   * Val's OWN publishes carry their message on the commit (`ValCommit`), and
+   * that is the one the Studio prefers — it is the message Val wrote. This is
+   * for every OTHER deployment: a developer's push, a merged pull request, a
+   * revert. Those have no Val commit at all, so without this the deploy feed
+   * could only name them by their short sha, and "what went out at 14:02?" had
+   * no answer inside the Studio.
+   *
+   * Optional AND nullable, and the two mean different things: absent is a
+   * content service that does not report messages (or an older one), null is
+   * one that reports having none. Both render as the short sha, so nothing
+   * depends on telling them apart — but a schema that demanded the field would
+   * reject the whole deployment feed of a service that does not send it.
+   */
+  commitMessage: z.string().nullable().optional()
+});
+
 /**
  * The wire shapes for reading history.
  *
@@ -1297,7 +1337,7 @@ var ValConfig = z.object({
   gitCommit: z.string().optional(),
   gitBranch: z.string().optional()
 });
-var ValidationFixZ = z.union([z.literal("image:add-metadata"), z.literal("image:check-metadata"), z.literal("image:check-remote"), z.literal("image:upload-remote"), z.literal("image:download-remote"), z.literal("images:check-remote"), z.literal("images:upload-remote"), z.literal("file:add-metadata"), z.literal("file:check-metadata"), z.literal("file:check-remote"), z.literal("file:upload-remote"), z.literal("file:download-remote"), z.literal("files:check-remote"), z.literal("files:upload-remote"), z.literal("keyof:check-keys"), z.literal("router:check-route"), z.literal("images:check-unique-folder"), z.literal("files:check-unique-folder"), z.literal("images:check-all-files"), z.literal("files:check-all-files"), z.literal("jsonValues:extract-entry")]);
+var ValidationFixZ = z.union([z.literal("image:add-metadata"), z.literal("image:check-metadata"), z.literal("image:check-remote"), z.literal("image:upload-remote"), z.literal("image:download-remote"), z.literal("images:check-remote"), z.literal("images:upload-remote"), z.literal("file:add-metadata"), z.literal("file:check-metadata"), z.literal("file:check-remote"), z.literal("file:upload-remote"), z.literal("file:download-remote"), z.literal("files:check-remote"), z.literal("files:upload-remote"), z.literal("keyof:check-keys"), z.literal("router:check-route"), z.literal("locale:check-locale"), z.literal("record:fill-keys"), z.literal("images:check-unique-folder"), z.literal("files:check-unique-folder"), z.literal("images:check-all-files"), z.literal("files:check-all-files"), z.literal("jsonValues:extract-entry")]);
 var ValidationError = z.object({
   message: z.string(),
   value: z.unknown().optional(),
@@ -1750,6 +1790,21 @@ var Api = {
            */
           headCommitSha: z.string().optional(),
           commits: z.array(ValCommit),
+          /**
+           * The publishes the content service knows about.
+           *
+           * Declared, at last. `getStat` has always returned these in
+           * `http` mode and the Studio has always read them - the response
+           * validator strips unknown keys rather than rejecting them, and
+           * the raw json is what the client hands back, so they arrived
+           * while the contract said they could not. That was survivable
+           * until a deployment started carrying a commit MESSAGE: a field
+           * nobody has declared is a field the next person deletes.
+           *
+           * Optional, because a content service that reports no
+           * deployments sends none.
+           */
+          deployments: z.array(ValDeployment).optional(),
           config: ValConfig,
           profileId: z.string().nullable(),
           mode: z.union([z.literal("http"), z.literal("fs")])
@@ -3189,7 +3244,7 @@ var compatible = {
  * `readonly Json[]` — so the check that reads naturally does not type. This
  * predicate is that check, said once.
  */
-function isJsonObject(value) {
+function isJsonObject$1(value) {
   return _typeof(value) === "object" && value !== null && !Array.isArray(value);
 }
 function incompatible(reason) {
@@ -3242,21 +3297,11 @@ function explainIncompatible(reason) {
  * not a failure: it is what makes the caller return `unknown` rather than guess.
  */
 function variantOf(schema, value) {
-  if (schema.type !== "union") {
+  if (schema.type !== "discriminated-union") {
     return undefined;
   }
-  // String union: the value IS the discriminator.
-  if (typeof schema.key !== "string") {
-    if (typeof value !== "string") {
-      return undefined;
-    }
-    return schema.items.find(function (item) {
-      return item.type === "literal" && item.value === value;
-    });
-  }
-  // Object union: the discriminator is a literal at `key`.
   var discriminator = schema.key;
-  if (!isJsonObject(value)) {
+  if (!isJsonObject$1(value)) {
     return undefined;
   }
   var tag = value[discriminator];
@@ -3272,9 +3317,6 @@ function variantOf(schema, value) {
   });
 }
 function describeVariant(schema, key) {
-  if (schema.type === "literal") {
-    return schema.value;
-  }
   if (schema.type === "object") {
     var tag = schema.items[key];
     if ((tag === null || tag === void 0 ? void 0 : tag.type) === "literal") {
@@ -3292,11 +3334,24 @@ function checkCompatibility(from, to) {
     });
   }
 
+  // An enum's domain IS its schema, so the value decides: whatever the old
+  // schema was — an enum, a literal, a plain string — the only question is
+  // whether this string is still offered here.
+  if (to.schema.type === "enum") {
+    if (typeof from.value === "string" && to.schema.values.includes(from.value)) {
+      return compatible;
+    }
+    return incompatible({
+      kind: "no-matching-variant",
+      variants: to.schema.values
+    });
+  }
+
   // A changed union is not itself disqualifying. What matters is whether the
   // variant being restored still has somewhere to go — comparing the unions
   // wholesale would refuse a restore that is perfectly safe.
-  if (to.schema.type === "union") {
-    var key = typeof to.schema.key === "string" ? to.schema.key : "";
+  if (to.schema.type === "discriminated-union") {
+    var key = to.schema.key;
     var _iterator = _createForOfIteratorHelper(to.schema.items),
       _step;
     try {
@@ -3321,9 +3376,9 @@ function checkCompatibility(from, to) {
     });
   }
 
-  // Coming FROM a union into something that is not one: only the variant this
-  // value actually is matters, so narrow before comparing.
-  if (from.schema.type === "union") {
+  // Coming FROM a discriminated union into something that is not one: only the
+  // variant this value actually is matters, so narrow before comparing.
+  if (from.schema.type === "discriminated-union") {
     var _variant = variantOf(from.schema, from.value);
     if (_variant === undefined) {
       return {
@@ -3336,6 +3391,25 @@ function checkCompatibility(from, to) {
       value: from.value
     }, to);
   }
+
+  // Coming FROM an enum into something that is not one: the value it holds is
+  // all the old schema contributes, so compare as that one value.
+  if (from.schema.type === "enum") {
+    if (typeof from.value !== "string") {
+      return {
+        status: "unknown",
+        message: "The old value is not one of the options it was stored as, so we cannot tell whether it fits here."
+      };
+    }
+    return checkCompatibility({
+      schema: {
+        type: "literal",
+        value: from.value,
+        opt: from.schema.opt
+      },
+      value: from.value
+    }, to);
+  }
   if (from.schema.type !== to.schema.type) {
     return incompatible({
       kind: "type-changed",
@@ -3355,7 +3429,7 @@ function checkCompatibility(from, to) {
       }
     case "object":
       {
-        if (from.schema.type !== "object" || !isJsonObject(from.value)) {
+        if (from.schema.type !== "object" || !isJsonObject$1(from.value)) {
           return {
             status: "unknown",
             message: "The old value is not shaped like an object."
@@ -3458,7 +3532,7 @@ function checkCompatibility(from, to) {
       }
     case "record":
       {
-        if (from.schema.type !== "record" || !isJsonObject(from.value)) {
+        if (from.schema.type !== "record" || !isJsonObject$1(from.value)) {
           return {
             status: "unknown",
             message: "The old value is not a record."
@@ -3569,14 +3643,6 @@ var SharedValConfig = z.object({
  * Config that is shared between the client and server.
  */
 
-var ValDeployment = z.object({
-  deploymentId: z.string(),
-  deploymentState: z.string(),
-  commitSha: z.string(),
-  updatedAt: z.string(),
-  createdAt: z.string()
-});
-
 /**
  * Shared route validation utilities
  */
@@ -3749,6 +3815,16 @@ function findSimilar(key, targets) {
     return a.distance - b.distance;
   });
 }
+/**
+ * The record a `keyof:check-keys` error resolves against — the value and the
+ * schema at the error's `sourcePath`.
+ *
+ * Exported for the one consumer that has to know what a resolution DEPENDED
+ * on rather than what it concluded: `ValidationStore` re-reads the keys here
+ * to decide whether a change to the referenced module can have moved the
+ * answer. Keep this and {@link checkKeyIsValid} reading the same record, or the
+ * store will invalidate on one record and the resolution answer from another.
+ */
 function getKeyOfRecordAt(sourcePath, snapshot) {
   var _Internal$splitModule = Internal.splitModuleFilePathAndModulePath(sourcePath),
     _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 2),
@@ -3892,16 +3968,92 @@ function checkRouteIsValid(route, includePattern, excludePattern, snapshot) {
     error: false
   };
 }
+
+/**
+ * The languages the project declares, from its settings module.
+ *
+ * Empty where there is no settings module, no `locales` section, or nothing in
+ * it — all of which mean the same thing: this project has not said it is
+ * translated.
+ */
+function declaredLocales(snapshot) {
+  var _resolveSettingsModul = resolveSettingsModule(snapshot.schemas),
+    moduleFilePath = _resolveSettingsModul.moduleFilePath;
+  if (moduleFilePath === null) {
+    return [];
+  }
+  var source = snapshot.sources[moduleFilePath];
+  if (_typeof(source) !== "object" || source === null || Array.isArray(source)) {
+    return [];
+  }
+  var locales = source["locales"];
+  if (_typeof(locales) !== "object" || locales === null || Array.isArray(locales)) {
+    return [];
+  }
+  var available = locales["available"];
+  if (!Array.isArray(available)) {
+    return [];
+  }
+  return available.filter(function (tag) {
+    return typeof tag === "string";
+  });
+}
+/**
+ * The fixes {@link resolveSchemaSourceFixForError} answers for.
+ *
+ * A marker error carrying one of these is NOT a message: it says "ask the whole
+ * project about this" and carries the value to ask with, because the schema
+ * that raised it can only see its own module. Left unresolved, what a user sees
+ * is the marker's own placeholder text — "should typically be processed by Val
+ * internally … version mismatch" — which is alarming and says nothing.
+ *
+ * A list rather than a check per call site: every caller that resolves some of
+ * these has to resolve all of them, and the two that leaked did so by adding a
+ * fix here and not to a condition somewhere else.
+ */
+var SCHEMA_SOURCE_FIXES = ["keyof:check-keys", "router:check-route", "locale:check-locale", "record:fill-keys"];
+
+/** Whether an error is a marker only the whole project can answer. */
+function isSchemaSourceFixError(error) {
+  var _error$fixes;
+  return ((_error$fixes = error.fixes) !== null && _error$fixes !== void 0 ? _error$fixes : []).some(function (fix) {
+    return SCHEMA_SOURCE_FIXES.includes(fix);
+  });
+}
+
 /**
- * Resolves a single `keyof:check-keys` or `router:check-route` error against
- * the given schema/source snapshot. Returns:
+ * The record a `keyof:check-keys` error resolves against, or null for any other
+ * error — including a malformed marker, which
+ * {@link resolveSchemaSourceFixForError} reports and this has nothing to say
+ * about.
+ *
+ * For a consumer that needs to know what the resolution READS, not what it
+ * concludes: `ValidationStore` keeps this per validated module, so that a change
+ * to the referenced record can invalidate the module holding the reference.
+ */
+function keyOfRecordPath(error) {
+  var _error$fixes2;
+  if (!((_error$fixes2 = error.fixes) !== null && _error$fixes2 !== void 0 ? _error$fixes2 : []).includes("keyof:check-keys")) {
+    return null;
+  }
+  var value = error.value;
+  if (!value || _typeof(value) !== "object") {
+    return null;
+  }
+  var sourcePath = value.sourcePath;
+  return typeof sourcePath === "string" ? sourcePath : null;
+}
+
+/**
+ * Resolves a single marker error (see {@link SCHEMA_SOURCE_FIXES}) against the
+ * given schema/source snapshot. Returns:
  *   - null if the error is not one of these fixes (caller should pass through)
- *   - { status: "resolved" } if the referenced key/route is valid (drop error)
+ *   - { status: "resolved" } if the reference is valid (drop error)
  *   - { status: "remaining"; error } if invalid (rewritten error to surface)
  */
 function resolveSchemaSourceFixForError(error, snapshot) {
-  var _error$fixes;
-  var fixes = (_error$fixes = error.fixes) !== null && _error$fixes !== void 0 ? _error$fixes : [];
+  var _error$fixes3;
+  var fixes = (_error$fixes3 = error.fixes) !== null && _error$fixes3 !== void 0 ? _error$fixes3 : [];
   if (fixes.includes("keyof:check-keys")) {
     if (!error.value) {
       return {
@@ -3960,6 +4112,120 @@ function resolveSchemaSourceFixForError(error, snapshot) {
       status: "resolved"
     };
   }
+  if (fixes.includes("locale:check-locale")) {
+    var value = error.value;
+    if (_typeof(value) !== "object" || value === null) {
+      return {
+        status: "remaining",
+        error: _objectSpread2(_objectSpread2({}, error), {}, {
+          message: "Expected locale validation error to have a 'value' object. Found: ".concat(_typeof(value), ". ").concat(TYPE_ERROR_MESSAGE),
+          typeError: true,
+          fixes: undefined
+        })
+      };
+    }
+    var _ref6 = value,
+      locale = _ref6.locale;
+    if (typeof locale !== "string") {
+      return {
+        status: "remaining",
+        error: _objectSpread2(_objectSpread2({}, error), {}, {
+          message: "Expected locale validation error 'value' to have property 'locale' of type 'string'. Found: ".concat(_typeof(locale), ". ").concat(TYPE_ERROR_MESSAGE),
+          typeError: true,
+          fixes: undefined
+        })
+      };
+    }
+    var available = declaredLocales(snapshot);
+    if (available.length === 0) {
+      return {
+        status: "remaining",
+        error: _objectSpread2(_objectSpread2({}, error), {}, {
+          // The project has not said it is translated, so the value is not
+          // wrong so much as premature — and the fix is in another file.
+          message: "This project has no languages. Declare them under 'locales.available' in the settings module before using s.locale().",
+          fixes: undefined
+        })
+      };
+    }
+    if (available.includes(locale)) {
+      return {
+        status: "resolved"
+      };
+    }
+    return {
+      status: "remaining",
+      error: _objectSpread2(_objectSpread2({}, error), {}, {
+        message: "'".concat(locale, "' is not one of this project's languages: ").concat(available.map(function (each) {
+          return "'".concat(each, "'");
+        }).join(", ")),
+        fixes: undefined
+      })
+    };
+  }
+  if (fixes.includes("record:fill-keys")) {
+    var _value = error.value;
+    if (_typeof(_value) !== "object" || _value === null) {
+      return {
+        status: "remaining",
+        error: _objectSpread2(_objectSpread2({}, error), {}, {
+          message: "Expected record key validation error to have a 'value' object. Found: ".concat(_typeof(_value), ". ").concat(TYPE_ERROR_MESSAGE),
+          typeError: true,
+          fixes: undefined
+        })
+      };
+    }
+    var _ref7 = _value,
+      present = _ref7.present,
+      declared = _ref7.declared;
+    if (!Array.isArray(present)) {
+      return {
+        status: "remaining",
+        error: _objectSpread2(_objectSpread2({}, error), {}, {
+          message: "Expected record key validation error 'value' to have property 'present' of type 'array'. Found: ".concat(_typeof(present), ". ").concat(TYPE_ERROR_MESSAGE),
+          typeError: true,
+          fixes: undefined
+        })
+      };
+    }
+    var presentKeys = present.filter(function (key) {
+      return typeof key === "string";
+    });
+    // A literal union brought its keys along; a locale record left them to be
+    // read out of the settings module, which is the whole reason this check is
+    // resolved here rather than in the schema.
+    var declaredKeys = Array.isArray(declared) ? declared.filter(function (key) {
+      return typeof key === "string";
+    }) : declaredLocales(snapshot);
+    if (declaredKeys.length === 0) {
+      // A locale record on a project that has declared no languages. There is
+      // nothing to require, and the locale field's own check already says the
+      // project has not declared any — saying it twice on one record would not
+      // add anything.
+      return {
+        status: "resolved"
+      };
+    }
+    var missing = missingDeclaredKeys(declaredKeys, presentKeys);
+    if (missing.length === 0) {
+      return {
+        status: "resolved"
+      };
+    }
+    return {
+      status: "remaining",
+      error: _objectSpread2(_objectSpread2({}, error), {}, {
+        message: "Missing ".concat(missing.length === 1 ? "key" : "keys", ": ").concat(missing.map(function (each) {
+          return "'".concat(each, "'");
+        }).join(", "), ". This record's keys are declared by its schema, so every one of them is an entry \u2014 an entry nobody has written yet is null, not absent."),
+        value: {
+          missing: missing,
+          declared: declaredKeys
+        },
+        fixes: undefined
+      })
+    };
+  }
   if (fixes.includes("router:check-route")) {
     if (!error.value) {
       return {
@@ -4021,10 +4287,10 @@ function asRegExpPattern(value) {
 /**
  * Apply schema/source fix resolution across a map of validation errors.
  *
- * Errors with `keyof:check-keys` or `router:check-route` are resolved against
- * the in-memory schema/source snapshot — valid references drop the error,
- * invalid ones are rewritten with a "did you mean…" message and have their
- * `fixes` cleared (so downstream code reports them as plain validation errors).
+ * Errors carrying one of {@link SCHEMA_SOURCE_FIXES} are resolved against the
+ * in-memory schema/source snapshot — valid references drop the error, invalid
+ * ones are rewritten with a "did you mean…" message and have their `fixes`
+ * cleared (so downstream code reports them as plain validation errors).
  * All other errors pass through untouched.
  *
  * Source paths with no remaining errors are removed from the result.
@@ -4058,6 +4324,189 @@ function resolveSchemaSourceFixes(validationErrors, snapshot) {
   return result;
 }
 
+/**
+ * Which of the project's languages governs a path, or `null` for none.
+ *
+ * THE question the whole feature turns on. A locale scope is a subtree in one
+ * language, and three things open one: a `locale` field on an object, a record
+ * keyed by `s.locale()`, and a locale segment in a segmented key. Once this can
+ * be answered from the schema and the source alone, everything downstream falls
+ * out of it — the Studio's locale filter, deep links, `<html lang>`, and knowing
+ * what to translate from and into.
+ *
+ * One implementation, so the Studio, the server and the validation worker cannot
+ * disagree about what language a piece of content is in.
+ *
+ * `null` means no scope governs the path — which is the answer for most content
+ * in most projects, and for every project that has not declared any languages.
+ */
+function localeAt(path, snapshot) {
+  var available = declaredLocales(snapshot);
+  if (available.length === 0) {
+    // Nothing can be one of no languages. Answering `null` rather than reading
+    // the content is also what makes this cheap for the projects that are not
+    // translated at all.
+    return null;
+  }
+  var _Internal$splitModule = Internal.splitModuleFilePathAndModulePath(path),
+    _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 2),
+    moduleFilePath = _Internal$splitModule2[0],
+    modulePath = _Internal$splitModule2[1];
+  var schema = snapshot.schemas[moduleFilePath];
+  var source = snapshot.sources[moduleFilePath];
+  if (schema === undefined || source === undefined) {
+    return null;
+  }
+  var segments = modulePath ? Internal.splitModulePath(modulePath) : [];
+  return walk(schema, source, segments, available);
+}
+
+/**
+ * Walk from a node towards `segments`, answering with the innermost scope.
+ *
+ * The scope is read on ARRIVAL at each node — the node the path names included,
+ * not only the ones passed through on the way to it. So `localeAt` of a
+ * scope-opening object is that object's own locale rather than its parent's,
+ * and a path that stops AT a block still answers with the block's language.
+ *
+ * A scope may not contain another (see `localeScopeErrors`), so at most one of
+ * these can fire on a well-formed path; taking the innermost is what makes the
+ * answer well-defined while a project is mid-fix.
+ */
+function walk(schema, source, segments, available) {
+  var entered = enter(schema, source, available);
+  var locale = entered.locale;
+  var currentSchema = entered.schema;
+  var currentSource = source;
+  var _iterator = _createForOfIteratorHelper(segments),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var segment = _step.value;
+      if (currentSchema === undefined) {
+        return locale;
+      }
+      if (currentSchema.type === "record") {
+        var _currentSchema$key;
+        if (((_currentSchema$key = currentSchema.key) === null || _currentSchema$key === void 0 ? void 0 : _currentSchema$key.type) === "locale") {
+          // In a locale-keyed record the KEY is the language, so the segment we
+          // are about to take is the answer.
+          var resolved = localeOfValue(segment, available);
+          if (resolved !== null) {
+            locale = resolved;
+          }
+        }
+        currentSchema = currentSchema.item;
+      } else if (currentSchema.type === "array") {
+        currentSchema = currentSchema.item;
+      } else if (currentSchema.type === "object" || currentSchema.type === "settings") {
+        currentSchema = currentSchema.items[segment];
+      } else {
+        // A leaf, or richtext's internal structure. Nothing below opens a scope.
+        return locale;
+      }
+      currentSource = childSource(currentSource, segment);
+      entered = enter(currentSchema, currentSource, available);
+      currentSchema = entered.schema;
+      if (entered.locale !== null) {
+        locale = entered.locale;
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return locale;
+}
+
+/**
+ * Arrive at a node: resolve what it really is, and read the scope it opens.
+ *
+ * A discriminated union is a fork rather than a level — the variant the value
+ * takes IS the node — so it is resolved here, before anything asks what the
+ * node holds. Doing that on arrival rather than on the way down is the
+ * difference between a block's own path answering with its language and
+ * answering with nothing.
+ */
+function enter(schema, source, available) {
+  var resolved = (schema === null || schema === void 0 ? void 0 : schema.type) === "discriminated-union" ? variantOfUnion(schema, source) : schema;
+  return {
+    schema: resolved,
+    locale: resolved === undefined ? null : localeOfObjectField(resolved, source, available)
+  };
+}
+
+/**
+ * The language an object's own `locale` field says it is in, if it has one.
+ *
+ * Reads the SOURCE, since unlike a record key the value is content rather than
+ * part of the path. A field that has not been filled in, or holds something
+ * that is not one of the project's languages, is not an answer — validation is
+ * already reporting that, and guessing here would put a language in
+ * `<html lang>` that nobody chose.
+ */
+function localeOfObjectField(schema, source, available) {
+  if (schema.type !== "object" || !isJsonObject(source)) {
+    return null;
+  }
+  for (var _i = 0, _Object$entries = Object.entries(schema.items); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      item = _Object$entries$_i[1];
+    if (item.type !== "locale") {
+      continue;
+    }
+    var value = source[key];
+    if (typeof value !== "string") {
+      return null;
+    }
+    return localeOfValue(value, available);
+  }
+  return null;
+}
+
+/**
+ * The variant a value takes, or `undefined` if the tag matches none.
+ *
+ * The tag is read off the source here; picking the variant is
+ * {@link discriminatedUnionBranchOf}, shared with the Studio's locale filter so
+ * the two cannot disagree about which variant a row is. `s.enum()` never
+ * reaches this — it is a leaf, with nothing under it to walk into.
+ */
+function variantOfUnion(schema, source) {
+  if (!isJsonObject(source)) {
+    return undefined;
+  }
+  return discriminatedUnionBranchOf(schema, source[schema.key]);
+}
+
+/** The child of a source value at a segment, or `null` where there is none. */
+function childSource(source, segment) {
+  var _source$segment;
+  if (Array.isArray(source)) {
+    var _source$index;
+    var index = Number(segment);
+    return Number.isInteger(index) ? (_source$index = source[index]) !== null && _source$index !== void 0 ? _source$index : null : null;
+  }
+  if (!isJsonObject(source)) {
+    return null;
+  }
+  return (_source$segment = source[segment]) !== null && _source$segment !== void 0 ? _source$segment : null;
+}
+
+/**
+ * Whether `source` is a JSON object rather than an array or a primitive.
+ *
+ * A type predicate rather than the inline checks, because `Array.isArray` does
+ * NOT narrow `JsonArray` out of `Json` — it is `readonly Json[]`, and the
+ * built-in guard only narrows mutable arrays. Without this, every read of a
+ * property would need an assertion.
+ */
+function isJsonObject(source) {
+  return _typeof(source) === "object" && source !== null && !Array.isArray(source);
+}
+
 /**
  * Local `yyyy-MM-dd`, which is the one thing this module used `date-fns` for.
  *
@@ -4094,15 +4543,27 @@ function clampDateTimeString(value, options) {
   }
   return value;
 }
-function emptyOf(schema) {
+
+/**
+ * What `emptyOf` cannot read off a serialized schema.
+ *
+ * The project's languages, and which one is being worked in. Neither is in the
+ * schema: a locale-keyed record has one entry per language and the languages
+ * are declared in the settings module, and "which language am I writing" is a
+ * fact about the editor, not about the content. Optional throughout: a caller
+ * that has no context gets an empty record and an unset locale, which
+ * validation then reports, rather than wrong ones.
+ */
+
+function emptyOf(schema, context) {
   if (schema.type === "object") {
     return Object.fromEntries(Object.keys(schema.items).map(function (key) {
-      return [key, emptyOf(schema.items[key])];
+      return [key, emptyOf(schema.items[key], context)];
     }));
   } else if (schema.type === "array") {
     return [];
   } else if (schema.type === "record") {
-    return {};
+    return emptyRecord(schema, context);
   } else if (schema.type === "settings") {
     // Not an object of empty sections: every settings key is optional, and
     // absent IS the empty value. Filling the sections in would write a shape
@@ -4126,15 +4587,34 @@ function emptyOf(schema) {
     }
   } else if (schema.type === "route") {
     return ""; // Empty string as default route value
+  } else if (schema.type === "locale") {
+    var _context$selectedLoca;
+    // Which languages exist is in the settings module, which `emptyOf` has no
+    // access to — it works from a serialized schema alone. So a caller that
+    // has narrowed to one language says so and gets it; a caller that has not
+    // gets the empty string, which is not a language and which validation
+    // reports. Guessing `locales[0]` instead would file content under a
+    // language nobody chose, which is the thing this whole feature exists to
+    // make visible.
+    return (_context$selectedLoca = context === null || context === void 0 ? void 0 : context.selectedLocale) !== null && _context$selectedLoca !== void 0 ? _context$selectedLoca : "";
   } else if (schema.type === "file" || schema.type === "image") {
     return null; // returning null is the only thing we can do, however, it means that the patches cannot be applied yet since that might fail
   } else if (schema.type === "literal") {
     return schema.value;
-  } else if (schema.type === "union") {
-    if (typeof schema.key === "string") {
-      return emptyOf(schema.items[0]);
+  } else if (schema.type === "discriminated-union") {
+    // The first variant is what a new value starts as. `s.discriminatedUnion`
+    // requires one, so an empty `items` means a serialized schema that was not
+    // built by it — say so rather than returning `undefined`, which is not
+    // JSON and would be written into a patch as a missing key.
+    if (schema.items.length === 0) {
+      throw Error("Cannot create an empty value for a discriminated union with no variants");
+    }
+    return emptyOf(schema.items[0], context);
+  } else if (schema.type === "enum") {
+    if (schema.values.length === 0) {
+      throw Error("Cannot create an empty value for an enum with no values");
     }
-    return schema.key.value;
+    return schema.values[0];
   } else if (schema.type === "date") {
     return clampDateString(formatLocalDate(new Date()), schema.options);
   } else if (schema.type === "dateTime") {
@@ -4155,6 +4635,32 @@ function emptyOf(schema) {
   throw Error("Unexpected schema type: " + JSON.stringify(_exhaustiveCheck));
 }
 
+/**
+ * An empty record — with every key its schema declares already in it.
+ *
+ * An open record (`s.record(s.string(), item)`) starts empty, because there is
+ * no key anyone could mean. A record whose key schema enumerates its keys is
+ * the opposite: the keys are part of the schema, so an empty one is already
+ * missing them, and handing back `{}` would create content that fails
+ * validation the moment it is written.
+ *
+ * The entries are `null` rather than `emptyOf(item)`. A null entry reads as "not
+ * filled in yet", which is what a language nobody has translated into IS —
+ * whereas an entry of empty strings claims someone wrote it and left it blank,
+ * and would count as translated in every list and filter downstream.
+ */
+function emptyRecord(schema, context) {
+  var _context$locales;
+  var declared = declaredKeySetOf(schema.key);
+  if (declared === null) {
+    return {};
+  }
+  var keys = declared.kind === "literals" ? declared.keys : (_context$locales = context === null || context === void 0 ? void 0 : context.locales) !== null && _context$locales !== void 0 ? _context$locales : [];
+  return Object.fromEntries(keys.map(function (key) {
+    return [key, null];
+  }));
+}
+
 var toolNames = ["get_all_schema", "get_source", "search_content", "validate_content", "create_patch", "add_session_image_to_gallery", "remove_image_gallery_entry", "navigate_to", "get_current_context", "get_patches", "get_source_path_from_route", "set_session_name", "show_compare_view", "ask_user_question", "duplicate_source", "empty_at_path", "count_entries", "get_record_keys"];
 
 function buildFileRefValue(filePath, metadata) {
@@ -4222,24 +4728,19 @@ function resolveSerializedSchemaAtPath(schema, path) {
         schema: current,
         remainingPath: path.slice(i)
       };
-    } else if (current.type === "union") {
-      if (typeof current.key === "string") {
-        var _iterator2 = _createForOfIteratorHelper(current.items),
-          _step2;
-        try {
-          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-            var variant = _step2.value;
-            var resolved = resolveSerializedSchemaAtPath(variant, path.slice(i));
-            if (resolved.kind !== "unresolved") return resolved;
-          }
-        } catch (err) {
-          _iterator2.e(err);
-        } finally {
-          _iterator2.f();
+    } else if (current.type === "discriminated-union") {
+      var _iterator2 = _createForOfIteratorHelper(current.items),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var variant = _step2.value;
+          var resolved = resolveSerializedSchemaAtPath(variant, path.slice(i));
+          if (resolved.kind !== "unresolved") return resolved;
         }
-        return {
-          kind: "unresolved"
-        };
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
       }
       return {
         kind: "unresolved"
@@ -4536,7 +5037,13 @@ function buildEmptyAtPathPatch(args, moduleSchema,
 // Required, not optional: the occupied-key check below is the only thing
 // standing between "scaffold an entry" and "delete the entry that was there",
 // and an optional argument is one a caller forgets.
-moduleSource) {
+moduleSource,
+// The project's languages, for a locale-keyed record: its entries ARE the
+// languages, and they are declared in another module, so an empty one built
+// without them is `{}` — which the completeness rule then reports as every
+// language missing. Both callers can answer: the Studio from the context, the
+// MCP tools from the snapshot they already hold. See `EmptyOfContext`.
+context) {
   var destinationSchema;
   if (args.destinationPath.length === 0) {
     destinationSchema = moduleSchema;
@@ -4582,7 +5089,7 @@ moduleSource) {
   if (occupied) {
     return occupied;
   }
-  var value = emptyOf(destinationSchema);
+  var value = emptyOf(destinationSchema, context);
   return safeParsePatch([{
     op: decision.op,
     path: args.destinationPath,
@@ -4773,6 +5280,8 @@ function isSkippableFixCode(fix) {
       return true;
     case "keyof:check-keys":
     case "router:check-route":
+    case "locale:check-locale":
+    case "record:fill-keys":
     case "jsonValues:extract-entry":
       // `jsonValues:extract-entry` is an entry inlined in the `.val.ts`. The
       // browser cannot fix it (that means writing a new `*.val.json` and
@@ -5168,8 +5677,20 @@ function traverseSchemaSource(source, schema, path, callback) {
     return;
   }
 
-  // Handle route
-  if (schema.type === "route") {
+  // Handle enum: a leaf, like a literal with more than one allowed value
+  if (schema.type === "enum") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle route and locale: both are plain strings at a leaf
+  if (schema.type === "route" || schema.type === "locale") {
     if (typeof source === "string") {
       callback({
         source: source,
@@ -5215,36 +5736,24 @@ function traverseSchemaSource(source, schema, path, callback) {
     return;
   }
 
-  // Handle union
-  if (schema.type === "union") {
+  // Handle discriminated union: descend through the variant the value takes
+  if (schema.type === "discriminated-union") {
     var schemaKey = schema.key;
-    if (typeof schemaKey === "string") {
-      // Tagged union - find matching sub-schema
-      if (source && _typeof(source) === "object" && !Array.isArray(source) && schemaKey in source) {
-        var itemKey = source[schemaKey];
-        if (typeof itemKey === "string") {
-          var schemaOfItem = schema.items.filter(function (item) {
-            return item.type === "object";
-          }).find(function (item) {
-            var itemKeySchema = item.items[schemaKey];
-            if ((itemKeySchema === null || itemKeySchema === void 0 ? void 0 : itemKeySchema.type) === "literal") {
-              return itemKeySchema.value === itemKey;
-            }
-            return false;
-          });
-          if (schemaOfItem) {
-            traverseSchemaSource(source, schemaOfItem, path, callback);
+    if (source && _typeof(source) === "object" && !Array.isArray(source) && schemaKey in source) {
+      var itemKey = source[schemaKey];
+      if (typeof itemKey === "string") {
+        var schemaOfItem = schema.items.filter(function (item) {
+          return item.type === "object";
+        }).find(function (item) {
+          var itemKeySchema = item.items[schemaKey];
+          if ((itemKeySchema === null || itemKeySchema === void 0 ? void 0 : itemKeySchema.type) === "literal") {
+            return itemKeySchema.value === itemKey;
           }
-        }
-      }
-    } else {
-      // Literal union - treat as primitive
-      if (typeof source === "string") {
-        callback({
-          source: source,
-          schema: schema,
-          path: path
+          return false;
         });
+        if (schemaOfItem) {
+          traverseSchemaSource(source, schemaOfItem, path, callback);
+        }
       }
     }
     return;
@@ -5404,7 +5913,17 @@ function indexModule(searchIndex, moduleFilePath, source, schema) {
     var label = "";
 
     // Handle primitives
-    if (schema.type === "string" || schema.type === "number" || schema.type === "boolean" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route") {
+    if (schema.type === "string" || schema.type === "number" || schema.type === "boolean" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" ||
+    // An enum's value is a string the editor chose; it is as searchable as
+    // any other string leaf. The old string union was never indexed at all,
+    // which is the gap this closes.
+    schema.type === "enum" ||
+    // A locale tag, for the same reason: it is what the editor picked and
+    // what they see in the field, so searching "nb-NO" has to find the
+    // Norwegian rows. `traverseSchemaSource` visits these, and visiting a
+    // leaf only to index it as the empty string is worse than not visiting
+    // it — it looks like content that does not exist.
+    schema.type === "locale") {
       var _source$toString, _source$toString2;
       searchText = (_source$toString = source === null || source === void 0 ? void 0 : source.toString()) !== null && _source$toString !== void 0 ? _source$toString : "";
       label = (_source$toString2 = source === null || source === void 0 ? void 0 : source.toString()) !== null && _source$toString2 !== void 0 ? _source$toString2 : "";
@@ -5545,4 +6064,4 @@ 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, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedUnionSchema, 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, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSkippedSource, levenshtein, newestCommitSha, partitionValidationErrors, performSearch, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+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 };