@valbuild/core 0.126.0 → 0.127.0

package/CHANGELOG.md

@@ -1,5 +1,189 @@
 # @valbuild/core
 
+## 0.127.0
+
+### Minor Changes
+
+- [#608](https://github.com/valbuild/val/pull/608) [`7fa8699`](https://github.com/valbuild/val/commit/7fa869974bc895af992a7d5c18b76253636d7d65) Thanks [@freekh](https://github.com/freekh)! - A record whose schema declares its keys now holds every one of them.
+
+  Two key schemas enumerate their keys: `s.locale()`, whose set is the project's
+  `locales.available`, and a union of literals. For those, the keys are part of the
+  schema, so a missing one is a hole in the content rather than content nobody has
+  written yet — and validation now says so, naming what is missing.
+
+  ```typescript
+  s.record(s.locale(), s.object({ title: s.string() }));
+  // Missing key: 'nb-NO'. This record's keys are declared by its schema, so
+  // every one of them is an entry — an entry nobody has written yet is null,
+  // not absent.
+  ```
+
+  **An entry nobody has written yet is `null`.** Not an absent key: a null entry is
+  data you can count, filter and see in a diff, and it means half-translated
+  content stays _valid_ rather than blocking a publish. The value type of such a
+  record widens by `null` to match, so writing one in a `.val.ts` type-checks:
+
+  ```typescript
+  c.define(
+    "/content/jacket.val.ts",
+    s.record(s.locale(), s.object({ title: s.string() })),
+    {
+      "en-US": { title: "Winter jacket" },
+      "nb-NO": null, // nobody has translated this yet
+    },
+  );
+  ```
+
+  **This changes `s.record(s.union(...), item)`**, and closes a gap that was
+  already there: `s.record(s.union(s.literal("a"), s.literal("b")), item)` types as
+  `Record<"a" | "b", T>`, so TypeScript demanded both keys while the validator only
+  checked the ones present. It now checks them too, and — as above — accepts `null`
+  for an entry that has not been filled in. If you have such a record with keys
+  missing, validation will report them; adding the keys with `null` values is the
+  fix, and creating one from the Studio does it for you.
+
+  `emptyOf` creates these records with every key already in them rather than
+  empty, since an empty one is already missing keys. In the Studio use the
+  `useEmptyOf()` hook rather than importing `emptyOf` directly: a locale record's
+  keys are in the settings module, and the hook is what has read it.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`5b7fe05`](https://github.com/valbuild/val/commit/5b7fe05cec6365f9cd1de9ba31e65ed4a87edb63) Thanks [@freekh](https://github.com/freekh)! - `s.locale()`: one of the project's languages.
+
+  The languages themselves are declared in the settings module (`locales.available`);
+  this says that a value is one of them.
+
+  ```typescript
+  // a field: everything in this entry is in this language
+  s.record(s.string(), s.object({ locale: s.locale(), title: s.string() }));
+
+  // a key: one entry per language
+  s.record(s.locale(), s.object({ title: s.string() }));
+  ```
+
+  Every locale in content is checked against the project's list, the way `keyOf`
+  and `route` are checked against what they point at. An undeclared language names
+  the ones the project has; a project that has declared none is told to declare
+  them rather than told the value is wrong.
+
+  A locale is stored as the tag itself — the value in content is `nb-NO`, and a
+  record keyed by `s.locale()` has `nb-NO` as its key. Spelling one differently
+  where it is stored (`/no/…` as a URL segment) is a real need and is deliberately
+  not in this release: it changes what is accepted as well as what is shown, so it
+  is being designed on its own rather than folded in here.
+
+  A locale is **never stega encoded**: it ends up in `<html lang>`, in `hreflang`
+  and in `Intl` constructors, none of which survive invisible characters.
+
+  `assistant.translation` joins the settings module alongside `context` and `tone`
+  — a note per language, keyed by language, so only the target language's rules are
+  sent when translating into it.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`88262ac`](https://github.com/valbuild/val/commit/88262ac8db068650a664981ef73556457d87741a) Thanks [@freekh](https://github.com/freekh)! - Locale scopes: a subtree in one language, and one function that answers which.
+
+  A **locale scope** is content governed by a single language. Two things open one
+  today (a third, locale segments in routes, follows):
+
+  ```typescript
+  // a locale field: this object and everything below it is in one language
+  s.object({ locale: s.locale(), title: s.string(), body: s.richtext() });
+
+  // a locale-keyed record: each entry is in the language its key names
+  s.record(s.locale(), s.object({ title: s.string() }));
+  ```
+
+  **A scope may not contain another scope**, and an object may have only one
+  locale field. Both are reported as schema errors, naming what to move:
+
+  ```
+  An object can be in one language, so it can have one locale field.
+  Found 'locale', 'language'.
+
+  Everything here is already in one language, so 'byLanguage' cannot set
+  another. Move the locale-keyed record out of this object, or take the outer
+  one away.
+  ```
+
+  A scope three levels deep is reported once, by the scope immediately enclosing
+  it, rather than by every ancestor.
+
+  The rule is **validated rather than typed**. Expressing "no scope below this
+  one" as a type constraint means threading it through every schema class's type
+  parameter, and the errors a recursive constraint like that produces name the
+  whole tree — an unrelated typo in a `.val.ts` would print pages.
+
+  `localeAt(path, snapshot)` (from `@valbuild/shared/internal`) answers which
+  language governs a path, and is the one implementation of that question, so the
+  Studio, the server and the validation worker cannot disagree. It returns the
+  tag, which is what `<html lang>`, `Intl` and `locales.available` all want.
+
+  It answers `null` where no scope governs the path, where the project has
+  declared no languages, and where a locale field holds something that is not one
+  of them — validation is already reporting the last, and guessing would put a
+  language in `<html lang>` that nobody chose.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`29811c3`](https://github.com/valbuild/val/commit/29811c3f8c7e001a950e6f4833af6888e6a4efea) Thanks [@freekh](https://github.com/freekh)! - Settings: declare the languages a project publishes.
+
+  A new `locales` section in the settings module says which languages a project
+  has:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    locales: {
+      available: ["en-US", "fr-FR", "nb-NO"],
+    },
+  });
+  ```
+
+  The order is the project's own and is kept rather than sorted: it is the order
+  of the Studio's locale picker and of the rows in a locale-keyed record. There
+  is no default language — every locale-specific field asks which language it is
+  in, and a default is the answer that lets that question go unanswered.
+
+  Like every other settings section it is optional, so a project that is not
+  translated writes nothing and sees nothing: no locale controls appear anywhere
+  until `available` has something in it.
+
+  This is content rather than configuration, and deliberately: which languages a
+  site has is a decision the people who write it make, and under a build-time
+  constant it took a developer and a deploy. It is the same move `assistant`
+  already makes with `enabled`.
+
+  Tags are BCP 47 (`en-US`, `nb-NO`), checked through `Intl.getCanonicalLocales` —
+  the same implementation `<html lang>` and every `Intl` constructor use — and
+  they have to be in canonical form. `nb-no` parses, but nothing else in the stack
+  agrees it is the same string as `nb-NO`, and a locale is compared as a string
+  everywhere it is used. Validation names the spelling to use, and reports a
+  language declared twice on the repeat rather than on the list — that is the row
+  to delete, and a message on the list itself would not say which.
+
+  Edited under Settings → Locales in the Studio, which names each language in its
+  own language.
+
+### Patch Changes
+
+- [#665](https://github.com/valbuild/val/pull/665) [`7072e07`](https://github.com/valbuild/val/commit/7072e07623c953a09ac14388ae22dada0b431ce3) Thanks [@freekh](https://github.com/freekh)! - `.nullable()` no longer drops the field's `.validate(...)` functions.
+
+  `.nullable()` returns a copy of the schema, and most of the schema classes built
+  that copy with an empty list of custom validators — so a validator declared
+  before the `.nullable()` was silently thrown away:
+
+  ```ts
+  s.number()
+    .validate((n) => (n > 100 ? "Too big" : false))
+    .nullable(); // the validator never ran
+  ```
+
+  `array`, `object`, `discriminatedUnion`, `enum`, `number`, `boolean`, `literal`,
+  `keyOf`, `date`, `dateTime`, `code`, `color` and `richtext` were affected;
+  `string`, `record`, `route`, `file` and `image` already carried them over, which
+  is why the bug was easy to miss. Validators now survive `.nullable()` on every
+  schema, in either order.
+
+  A validator on a nullable schema is called with `null` when the value is unset,
+  rather than being skipped — the same thing the schemas that never dropped them
+  have always done. If yours was written before the `.nullable()`, its argument is
+  typed as non-null even though `null` can reach it, so guard for it.
+
 ## 0.126.0
 
 ### Minor Changes

package/dist/declarations/src/index.d.ts

@@ -54,8 +54,12 @@ export { type SerializedImageSchema, ImageSchema } from "./schema/image.js";
 export { type SerializedFileSchema, FileSchema } from "./schema/file.js";
 export { type SerializedDateSchema, DateSchema } from "./schema/date.js";
 export { type SerializedSettingsSchema, SettingsSchema, } from "./schema/settings.js";
-export { type SettingsSource, type AssistantSettingsSource, type AssistantAvailability, ASSISTANT_SETTINGS_MAX_LENGTH, assistantAvailability, } from "./source/settings.js";
+export { type SettingsSource, type AssistantSettingsSource, type LocalesSettingsSource, type AssistantAvailability, ASSISTANT_SETTINGS_MAX_LENGTH, assistantAvailability, } from "./source/settings.js";
 export { type ResolvedSettingsModule, SETTINGS_MODULE_CONVENTION, isRootModuleFilePath, resolveSettingsModule, } from "./settingsModule.js";
+export { type Locale, localeTagError, localeOfValue } from "./locale.js";
+export { type SerializedLocaleSchema, LocaleSchema } from "./schema/locale.js";
+export { type DeclaredKeySet, declaredKeySetOf, missingDeclaredKeys, } from "./schema/declaredKeys.js";
+export { discriminatedUnionBranchOf } from "./schema/discriminatedUnionBranch.js";
 export { type SerializedColorSchema, type ColorOptions, ColorSchema, } from "./schema/color.js";
 export { type SerializedCodeSchema, type CodeOptions, type CodeLanguage, CodeSchema, CODE_LANGUAGES, } from "./schema/code.js";
 export { type ColorFormat, type ParsedColor, COLOR_FORMATS, DEFAULT_COLOR_FORMAT, } from "./schema/colorFormat.js";

package/dist/declarations/src/initSchema.d.ts

@@ -17,6 +17,7 @@ import { date } from "./schema/date.js";
 import { datetime } from "./schema/datetime.js";
 import { code } from "./schema/code.js";
 import { color } from "./schema/color.js";
+import { locale } from "./schema/locale.js";
 import { route } from "./schema/route.js";
 import { router } from "./schema/router.js";
 import { images } from "./schema/images.js";
@@ -266,6 +267,20 @@ export type InitSchema = {
      * ```
      */
     readonly route: typeof route;
+    /**
+     * Define one of the project's languages.
+     *
+     * The languages themselves are declared in the settings module, under
+     * `locales.available` — this says only that a value is one of them, which is
+     * checked against that list.
+     *
+     * @example // a field: everything under this object is in this language
+     * const schema = s.object({ locale: s.locale(), title: s.string() });
+     *
+     * @example // a key: one entry per language
+     * const schema = s.record(s.locale(), s.object({ title: s.string() }));
+     */
+    readonly locale: typeof locale;
     /**
      * Create a page router.
      * Each key is the path of the page.
@@ -393,6 +408,7 @@ export declare function initSchema(): {
     datetime: (options?: Record<string, never>) => import("./index.js").DateTimeSchema<import("./index.js").RawString>;
     color: (options?: import("./index.js").ColorOptions) => import("./index.js").ColorSchema<import("./index.js").RawString>;
     code: (options?: import("./index.js").CodeOptions) => import("./index.js").CodeSchema<import("./index.js").RawString>;
+    locale: () => import("./index.js").LocaleSchema<string>;
     route: <T extends string>(options?: Record<string, never>) => import("./index.js").RouteSchema<T>;
     router: typeof router;
     images: <Accept extends `image/${string}`>(options: import("./schema/images.js").ImagesOptions<Accept>) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{

package/dist/declarations/src/locale.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Language tags, and what makes one wrong.
+ *
+ * Val does not ship a list of locales. Which languages a project publishes is a
+ * property of that project, so it is declared in the settings module — see
+ * `LocalesSettingsSource` — and everything downstream reads it from there.
+ *
+ * What Val does own is the SPELLING. A tag is checked against BCP 47
+ * (RFC 5646) through `Intl.getCanonicalLocales`, which is the same
+ * implementation the browser, `<html lang>` and every `Intl` constructor use.
+ * Delegating rather than writing a matcher is the point: a tag this accepts is
+ * a tag those accept.
+ */
+/**
+ * What is wrong with `tag` as a language tag, or `false` if nothing is.
+ *
+ * Canonical form, not merely parseable, and the difference is what makes this
+ * worth checking at all. `nb-no` parses; `Intl.DisplayNames` and a
+ * case-sensitive comparison against a stored key do not agree about it. Since a
+ * locale is compared as a string everywhere — a record key, a URL segment, a
+ * value in content — one spelling has to win, and the canonical one is the
+ * spelling every other tool already produces.
+ *
+ * The message names the canonical form where there is one, because "not
+ * canonical" is not an instruction and `nb-NO` is.
+ */
+export declare function localeTagError(tag: string): string | false;
+/**
+ * A language tag, as content holds it.
+ *
+ * A *flavoured* string rather than a union or a strict brand. Which languages a
+ * project has is declared in its settings module, where the project can change
+ * it, so there is no set for a type to enumerate — and a strict brand would make
+ * `"nb-NO"` unassignable, which would mean writing every locale in a `.val.ts`
+ * through a constructor. Content stays plain data.
+ *
+ * So this carries no compile-time guarantee, and is not meant to. It names the
+ * concept where a bare `string` would say nothing, and the guarantee is the
+ * `locale:check-locale` validation against `locales.available`.
+ */
+declare const localeBrand: unique symbol;
+export type Locale = string & {
+    readonly [localeBrand]?: "locale";
+};
+/**
+ * The locale a stored value means, or `null` if it means none of them.
+ *
+ * A lookup against the project's languages, and today that is all it is. It
+ * stays a named function because it is the one place the question is asked —
+ * the Studio, the validation worker and the server all come here rather than
+ * comparing strings themselves, so they cannot disagree about what a stored
+ * value is.
+ */
+export declare function localeOfValue(value: string, available: readonly string[]): string | null;
+export {};

package/dist/declarations/src/schema/array.d.ts

@@ -85,6 +85,10 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     nullable(): ArraySchema<T, Src | null>;
     readonly(isReadonly?: boolean): ArraySchema<T, Src>;
     hidden(isHidden?: boolean): ArraySchema<T, Src>;
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
     protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;

package/dist/declarations/src/schema/declaredKeys.d.ts

@@ -0,0 +1,37 @@
+import { SerializedSchema } from "./index.js";
+/**
+ * The keys a record is REQUIRED to hold, where its key schema says what they are.
+ *
+ * Most records have an open key set — `s.record(s.string(), item)` holds
+ * whatever anyone adds — and this returns `null` for those. A record keyed by
+ * something that enumerates its values is different in kind: the keys are part
+ * of the schema, so a missing one is a hole in the content rather than content
+ * nobody has written yet.
+ *
+ * Two key schemas enumerate. A union of literals does it locally, so its keys
+ * are here. `s.locale()` does it in the settings module, which is another file
+ * and so cannot be read from a serialized schema — that case says only which
+ * kind it is, and is resolved against `locales.available` by
+ * `resolveSchemaSourceFixes`, the same crossing `keyOf` and `route` make.
+ */
+export type DeclaredKeySet = {
+    kind: "literals";
+    keys: string[];
+} | {
+    kind: "locale";
+};
+/**
+ * What `key` requires a record to hold, or `null` where it requires nothing.
+ *
+ * Works from the SERIALIZED schema so that the Studio, the validation worker
+ * and the server all answer this the same way — none of them has the schema
+ * instance, and `SchemaStore` deliberately holds serialized schemas only.
+ */
+export declare function declaredKeySetOf(key: SerializedSchema | undefined): DeclaredKeySet | null;
+/**
+ * The declared keys a record is missing, in the order the schema declares them.
+ *
+ * Declaration order rather than the source's: this is read as "what is left to
+ * write", and the answer should not reshuffle itself as entries are added.
+ */
+export declare function missingDeclaredKeys(declared: readonly string[], present: readonly string[]): string[];

package/dist/declarations/src/schema/discriminatedUnion.d.ts

@@ -114,6 +114,10 @@ export declare class DiscriminatedUnionSchema<Key extends string, T extends Disc
     nullable(): DiscriminatedUnionSchema<Key, T, Src | null>;
     readonly(isReadonly?: boolean): DiscriminatedUnionSchema<Key, T, Src>;
     hidden(isHidden?: boolean): DiscriminatedUnionSchema<Key, T, Src>;
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * The variant schema a value takes. `null` when the value matches none of

package/dist/declarations/src/schema/discriminatedUnionBranch.d.ts

@@ -0,0 +1,20 @@
+import { SerializedSchema } from "./index.js";
+/**
+ * The variant of a discriminated union that a value takes, by its tag.
+ *
+ * A discriminated union is a fork rather than a level: the variant IS the node,
+ * and everything a caller wants to know about that node — its fields, its
+ * `locale` field, the schema to draw it with — is on the variant and not on the
+ * union. Resolving it takes the source, so it cannot be done from the schema
+ * alone, which is why every caller that has only the union ends up needing this.
+ *
+ * `undefined` where the tag matches nothing, rather than a fallback to the first
+ * variant: a value whose tag names no variant is not a member of the union,
+ * validation is already saying so, and reading fields out of the wrong shape
+ * would answer confidently and wrongly.
+ *
+ * `s.enum()` never reaches here — it is a leaf whose values are strings, with no
+ * variants to resolve — so anything that is not a discriminated union answers
+ * `undefined` too.
+ */
+export declare function discriminatedUnionBranchOf(schema: SerializedSchema | undefined, tag: unknown): SerializedSchema | undefined;

package/dist/declarations/src/schema/enum.d.ts

@@ -38,6 +38,15 @@ export declare class EnumSchema<Src extends string | null> extends Schema<Src> {
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
+    /**
+     * Type-only marker: as a record key, this declares the key set.
+     *
+     * An enum names every value it may take, so a record keyed by one holds
+     * exactly those keys — the same claim `s.literal()` and `s.locale()` make.
+     * `DiscriminatedUnionSchema` carries no marker: it discriminates objects and
+     * cannot be a record key at all. See `LocaleSchema`.
+     */
+    readonly __declaresRecordKeys: true;
     constructor(values: readonly string[], opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.

package/dist/declarations/src/schema/index.d.ts

@@ -17,13 +17,14 @@ import { SerializedCodeSchema } from "./code.js";
 import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
+import { SerializedLocaleSchema } from "./locale.js";
 import { SerializedRouteSchema } from "./route.js";
 import { SerializedSettingsSchema } from "./settings.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
 import { ReifiedPreview, PreviewScope, PreviewItem } from "../preview.js";
-export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedSettingsSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;
@@ -74,6 +75,88 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * against the real instance. Structural errors publish first; these merge in.
      */
     protected abstract executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * Whether this node is a locale — the field that MARKS a scope, `s.locale()`.
+     *
+     * Only `LocaleSchema` overrides this. A base implementation rather than an
+     * abstract one on purpose: every other schema class answers no, and a
+     * question every class had to answer would be twenty edits for one yes.
+     *
+     * Not the same question as {@link opensLocaleScope}: a locale field marks the
+     * scope, the object AROUND it is the scope. See `localeScope.ts`.
+     */
+    protected isLocaleField(): boolean;
+    /**
+     * Whether this node OPENS a locale scope, and what opens it.
+     *
+     * An object with a `s.locale()` field opens one; so does a record keyed by
+     * `s.locale()`. Everything below such a node is in that one language, which
+     * is why a scope may not contain another — see `localeScope.ts` for the rule
+     * and the reason it is validated rather than typed.
+     */
+    protected opensLocaleScope(): "field" | "key" | null;
+    /**
+     * The child schemas a locale scope reaches, by the path segment that reaches
+     * them.
+     *
+     * A structural walk that deliberately does NOT go through `executeSerialize`:
+     * serializing a subtree at every node to ask a question about its shape is
+     * quadratic, and this is asked during validation. `*` stands for the item of
+     * an array or record, which has no name of its own.
+     */
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
+    /**
+     * Every locale scope opened strictly BELOW this node, by path.
+     *
+     * Stops descending at each one it finds, so a scope three deep is reported
+     * once, by the scope immediately enclosing it, rather than by every ancestor.
+     */
+    protected localeScopesBelow(prefix?: string[]): {
+        path: string[];
+        kind: "field" | "key";
+    }[];
+    /**
+     * The scope rule, as errors at this node — or `false` if it is not broken.
+     *
+     * Two things are wrong and both are wrong in the SCHEMA rather than in the
+     * content, so both are `schemaError`s: an object with two locale fields (the
+     * subtree below it would be in two languages at once), and a locale scope
+     * inside another (the inner one would silently override the outer for part
+     * of a subtree that is supposed to be one language throughout).
+     *
+     * Validated rather than typed on purpose. Expressing "no scope below this
+     * one" as a constraint means threading it through every schema class's type
+     * parameter, and the errors that fall out of a recursive constraint like
+     * that name the whole tree — an unrelated typo in a `.val.ts` would print
+     * pages. See the design notes on the locales PR.
+     */
+    protected localeScopeErrors(): ValidationError[];
+    /**
+     * The answer, computed once per schema.
+     *
+     * Memoised because the question is asked from `executeValidate`, which runs
+     * once per SOURCE instance: an array of five hundred blocks asks the item
+     * schema five hundred times, and each answer walks the schema below it
+     * looking for a nested scope. The answer cannot differ between two instances
+     * of the same schema — nothing here reads the source — so the walk is done
+     * once and the result handed back after that.
+     *
+     * The error is still reported at every instance's path. Val's validation
+     * errors are keyed by source path and that is where the Studio draws them, so
+     * a schema error on a row is a schema error on every row; reporting it on one
+     * arbitrary row would put it somewhere nobody was looking.
+     */
+    private localeScopeErrorsMemo?;
+    private computeLocaleScopeErrors;
+    /**
+     * This node's own `s.locale()` fields, where it is an object that has any.
+     *
+     * Empty everywhere else, so `localeScopeErrors` can live on the base class.
+     */
+    protected localeFieldNames(): string[];
     protected executeCustomValidateFunctions(src: Src, customValidateFunctions: CustomValidateFunction<Src>[], ctx: {
         path: SourcePath;
     }): ValidationError[];
@@ -99,8 +182,38 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * The editor gets a way to clear the field, and the type of the source
      * widens to include `null` — so consuming code has to handle it.
      *
-     * Declare `.validate(...)` AFTER `.nullable()`: on most schema types a
-     * validator added before it is not carried over.
+     * `.validate(...)` may be declared before or after `.nullable()`: the
+     * validator is carried over either way. Declared before, its argument is
+     * typed as non-null even though `null` can reach it, so guard for it.
+     *
+     * Implementations MUST carry `customValidateFunctions` over to the new
+     * instance. `.nullable()` returns a copy, so dropping them there silently
+     * un-declares the user's `.validate(...)` whenever it was written before the
+     * `.nullable()` — which is the order most people write it in. Thirteen schema
+     * classes passed `[]` here until this was fixed; `nullableCustomValidate.test.ts`
+     * pins one instance of every factory on `s` against that, and does not compile
+     * until a newly added schema is listed in it.
+     *
+     * The validators keep running when the value IS null: a nullable schema's
+     * validator sees `Src | null` and decides for itself. That is what the
+     * classes that never dropped them (string, record, route, file, image) have
+     * always done.
+     *
+     * Carrying them over needs a cast, because `Src` sits in a PARAMETER position
+     * of {@link CustomValidateFunction} and so `CustomValidateFunction<Src>[]` is
+     * not assignable to `CustomValidateFunction<Src | null>[]`. Widening what the
+     * functions can be CALLED with is the intent here rather than something the
+     * cast gets away with: `null` is handed to them, and the paragraph above is
+     * the behaviour that buys.
+     *
+     * A validator's parameter type was never a runtime guarantee to begin with.
+     * `executeValidate` runs the custom validators BEFORE the structural checks
+     * (see {@link CustomValidateFunction}'s callers, e.g. `NumberSchema`, which
+     * calls them ahead of its `typeof src !== "number"`), so one can already be
+     * called with a value of the wrong type entirely — hand-written content, or
+     * a node the Studio's walker reached before its type was checked. That is why
+     * {@link executeCustomValidateFunctions} catches what a validator throws and
+     * reports it as a `schemaError` instead of letting it escape.
      *
      * @example
      * const schema = s.object({

package/dist/declarations/src/schema/literal.d.ts

@@ -25,6 +25,8 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
+    /** Type-only marker: as a record key, this declares the key set. See `LocaleSchema`. */
+    readonly __declaresRecordKeys: true;
     constructor(value: string, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.