@valbuild/shared 0.126.0 → 0.128.0

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

@@ -1,6 +1,6 @@
-import { Internal, CODE_LANGUAGES, DEFAULT_COLOR_FORMAT } 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 { 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 _typeof, s as _defineProperty } from '../../dist/getSitemapTree-6777bdfa.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-6777bdfa.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), {}, {
@@ -1118,6 +1166,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 +1201,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, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, 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(),
@@ -1322,7 +1385,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(),
@@ -3229,7 +3292,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) {
@@ -3286,7 +3349,7 @@ function variantOf(schema, value) {
     return undefined;
   }
   var discriminator = schema.key;
-  if (!isJsonObject(value)) {
+  if (!isJsonObject$1(value)) {
     return undefined;
   }
   var tag = value[discriminator];
@@ -3414,7 +3477,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."
@@ -3517,7 +3580,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."
@@ -3953,6 +4016,59 @@ 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);
+  });
+}
+
 /**
  * The record a `keyof:check-keys` error resolves against, or null for any other
  * error — including a malformed marker, which
@@ -3964,8 +4080,8 @@ function checkRouteIsValid(route, includePattern, excludePattern, snapshot) {
  * to the referenced record can invalidate the module holding the reference.
  */
 function keyOfRecordPath(error) {
-  var _error$fixes;
-  if (!((_error$fixes = error.fixes) !== null && _error$fixes !== void 0 ? _error$fixes : []).includes("keyof:check-keys")) {
+  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;
@@ -3977,15 +4093,15 @@ function keyOfRecordPath(error) {
 }
 
 /**
- * Resolves a single `keyof:check-keys` or `router:check-route` error against
- * the given schema/source snapshot. Returns:
+ * 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$fixes2;
-  var fixes = (_error$fixes2 = error.fixes) !== null && _error$fixes2 !== void 0 ? _error$fixes2 : [];
+  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 {
@@ -4044,6 +4160,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 {
@@ -4105,10 +4335,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.
@@ -4142,6 +4372,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.
  *
@@ -4178,15 +4591,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
@@ -4210,6 +4635,16 @@ 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") {
@@ -4222,7 +4657,7 @@ function emptyOf(schema) {
     if (schema.items.length === 0) {
       throw Error("Cannot create an empty value for a discriminated union with no variants");
     }
-    return emptyOf(schema.items[0]);
+    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");
@@ -4248,6 +4683,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) {
@@ -4284,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.
@@ -4415,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
@@ -4478,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;
 }
@@ -4624,7 +5085,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;
@@ -4670,7 +5137,7 @@ moduleSource) {
   if (occupied) {
     return occupied;
   }
-  var value = emptyOf(destinationSchema);
+  var value = emptyOf(destinationSchema, context);
   return safeParsePatch([{
     op: decision.op,
     path: args.destinationPath,
@@ -4861,6 +5328,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
@@ -5268,8 +5737,8 @@ function traverseSchemaSource(source, schema, path, callback) {
     return;
   }
 
-  // Handle route
-  if (schema.type === "route") {
+  // 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,
@@ -5496,7 +5965,13 @@ function indexModule(searchIndex, moduleFilePath, source, schema) {
     // 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") {
+    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 : "";
@@ -5637,4 +6112,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, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, 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, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSkippedSource, keyOfRecordPath, 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 };