@valbuild/core 0.126.0 → 0.128.0

package/CHANGELOG.md

@@ -1,5 +1,301 @@
 # @valbuild/core
 
+## 0.128.0
+
+### Minor Changes
+
+- [#637](https://github.com/valbuild/val/pull/637) [`8b52b33`](https://github.com/valbuild/val/commit/8b52b33e1f629f14f66cc71dcc7cf415d210c7d4) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** the `directory` option is now `dir`, on every schema that takes
+  it — `s.imageset()`, `s.fileset()` and `s.image()`.
+
+  ```ts
+  // before
+  s.imageset({ directory: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", directory: "/public/val/docs" });
+  s.image({ directory: "/public/val/heroes" });
+
+  // after
+  s.imageset({ dir: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", dir: "/public/val/docs" });
+  s.image({ dir: "/public/val/heroes" });
+  ```
+
+  Same meaning: where uploads for that schema land. Still required on
+  `s.imageset()` and `s.fileset()`, still optional on `s.image()`.
+
+  **`files.directory` in `val.config.ts` is NOT renamed.** That is the
+  project-wide files directory, a different option with a different scope, and it
+  keeps its name.
+
+  `dir` is the serialized name too, and two things follow from that. Neither
+  needs any action, but both are worth knowing:
+
+  - **History still reads pre-rename commits.** A commit record stores the schema
+    each module was under, so commits from before this release carry `directory`.
+    The serialized-schema parser accepts that key and reads it as `dir`, which is
+    what keeps a historical gallery from showing up with no directory at all.
+  - **Published remote files re-validate once.** The serialized schema is what a
+    remote file's validation hash is computed from, so a file uploaded under a
+    schema that sets this option gets one re-download and re-check, after which
+    the ref is rewritten with the new hash. This is the same self-healing path a
+    core version bump already takes.
+
+- [#643](https://github.com/valbuild/val/pull/643) [`362fb49`](https://github.com/valbuild/val/commit/362fb49f30d2b04c4ff78d54dca2bf5ad978a05c) Thanks [@freekh](https://github.com/freekh)! - `s.imageset({ alt })` now types an entry's `alt` from the `alt` schema, instead
+  of always calling it `string | null`.
+
+  That single hard-coded type made the locale-record form **unusable** and the
+  required form **unsound**, in opposite directions:
+
+  ```ts
+  // Before: documented, but the source could not be typed.
+  //   Type '{ en: string; no: string; }' is not assignable to type 'string'
+  s.imageset({ dir: "/public/val/img", alt: s.record(s.string()) });
+
+  // Before: this compiled, then failed validation with
+  //   Expected 'string', got 'null'
+  s.imageset({ dir: "/public/val/img", alt: s.string() });
+  // → { width, height, mimeType, alt: null }
+  ```
+
+  Both now behave as the schema says: a locale record types as
+  `Record<string, string>`, a required alt as `string`, and an omitted or
+  `.nullable()` alt as `string | null` exactly as before.
+
+  `ImagesetEntryMetadata` takes an optional alt parameter and defaults to
+  `string | null`, so existing references keep working unchanged. Where a gallery
+  of any alt shape is acceptable — `s.image(galleryModule)` is the one that
+  matters, since a field carries its own alt and never reads the gallery's — write
+  `ImagesetEntryMetadata<AltSource>`.
+
+  The one thing to know if you had worked around this: an explicit
+  `Record<string, ImagesetEntryMetadata>` annotation on the source of a
+  **required**-alt gallery is now too wide and will not compile. Name the alt type
+  (`ImagesetEntryMetadata<string>`), or drop the annotation and let the schema
+  type it.
+
+- [#637](https://github.com/valbuild/val/pull/637) [`c595799`](https://github.com/valbuild/val/commit/c59579977a436ec530c6c69f2b340ab9829d97ab) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.images()` is now `s.imageset()`, and `s.files()` is now
+  `s.fileset()`.
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images" });
+  s.files({ accept: "application/pdf", directory: "/public/val/docs" });
+
+  // after
+  s.imageset({ dir: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", dir: "/public/val/docs" });
+  ```
+
+  Nothing about their behaviour changed — same `.remote()`, same
+  record-of-metadata content keyed by file path. (`directory` is renamed to
+  `dir` in the same release; see the separate note.)
+
+  The old names were a trap. `s.images()` and `s.image()` differ by one letter,
+  which reads as "the same thing, but several" — while the real difference is that
+  `s.imageset()` defines a **whole module** and `s.image()` defines a **field**.
+  They are not variants of each other, and the plural spelling suggested they were.
+  `-set` names the container instead, so the two now look as different as they are.
+
+  `s.image(imagesetModule)` and `s.file(filesetModule)` are unchanged: that is
+  still how a field picks one entry out of a set.
+
+  If you are also moving off the `remote` option (removed in the same release),
+  the combined migration is:
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images", remote: true });
+
+  // after
+  s.imageset({ dir: "/public/val/images" }).remote();
+  ```
+
+  The rename is a hard error rather than a silent one: `s.images` no longer
+  exists, so an un-migrated call fails immediately in TypeScript and at runtime.
+
+## 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

@@ -12,14 +12,15 @@ import { literal } from "./schema/literal.js";
 import { keyOf } from "./schema/keyOf.js";
 import { record } from "./schema/record.js";
 import { file } from "./schema/file.js";
-import { files } from "./schema/files.js";
+import { fileset } from "./schema/fileset.js";
 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";
+import { imageset } from "./schema/imageset.js";
 import { settings } from "./schema/settings.js";
 export type InitSchema = {
     /**
@@ -147,7 +148,7 @@ export type InitSchema = {
      *
      * @example
      * // Backed by a gallery: width, height and mimeType live there.
-     * import galleryVal from "./gallery.val"; // an s.images() module
+     * import galleryVal from "./gallery.val"; // an s.imageset() module
      * const schema = s.image(galleryVal);
      * export default c.define("/example.val.ts", schema, {
      *   path: "/public/val/example.png",
@@ -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.
@@ -296,9 +311,9 @@ export type InitSchema = {
      *
      * @example
      * ```typescript
-     * const schema = s.images({
+     * const schema = s.imageset({
      *   accept: "image/webp",
-     *   directory: "/public/val/images",
+     *   dir: "/public/val/images",
      *   alt: s.string().minLength(4),
      * });
      * export default c.define("/content/images.val.ts", schema, {
@@ -311,15 +326,15 @@ export type InitSchema = {
      * });
      * ```
      */
-    readonly images: typeof images;
+    readonly imageset: typeof imageset;
     /**
      * Define a collection of files.
      *
      * @example
      * ```typescript
-     * const schema = s.files({
+     * const schema = s.fileset({
      *   accept: "application/pdf",
-     *   directory: "/public/val/documents",
+     *   dir: "/public/val/documents",
      * });
      * export default c.define("/content/documents.val.ts", schema, {
      *   "/public/val/documents/report.pdf": {
@@ -328,7 +343,7 @@ export type InitSchema = {
      * });
      * ```
      */
-    readonly files: typeof files;
+    readonly fileset: typeof fileset;
     /**
      * Define the project's settings.
      *
@@ -384,27 +399,28 @@ export declare function initSchema(): {
     keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./index.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./index.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./index.js").RawString : never : never>;
     record: typeof record;
     file: typeof file;
-    files: (options: import("./schema/files.js").FilesOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
+    fileset: (options: import("./schema/fileset.js").FilesetOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
         mimeType: import("./index.js").StringSchema<string>;
     }, {
         mimeType: string;
-    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/files.js").FilesEntryMetadata>>;
+    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/fileset.js").FilesetEntryMetadata>>;
     date: (options?: Record<string, never>) => import("./index.js").DateSchema<import("./index.js").RawString>;
     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<{
+    imageset: <Accept extends `image/${string}`, Alt extends import("./schema/imageset.js").AltSchema = import("./index.js").StringSchema<string | null>>(options: import("./schema/imageset.js").ImagesetOptions<Accept, Alt>) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
         width: import("./index.js").NumberSchema<number>;
         height: import("./index.js").NumberSchema<number>;
         mimeType: import("./index.js").StringSchema<string>;
-        alt: import("./index.js").StringSchema<string | null>;
+        alt: Alt;
     }, {
         width: number;
         height: number;
         mimeType: string;
-        alt: string | null;
-    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/images.js").ImagesEntryMetadata>>;
+        alt: import("./schema/index.js").SelectorOfSchema<Alt>;
+    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/imageset.js").ImagesetEntryMetadata<import("./schema/imageset.js").AltSourceOf<Alt>>>>;
     settings: typeof settings;
 };

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/file.d.ts

@@ -6,7 +6,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { FieldRender } from "../render.js";
-import { FilesEntryMetadata } from "./files.js";
+import { FilesetEntryMetadata } from "./fileset.js";
 export type FileOptions = {
     accept?: string;
 };
@@ -36,7 +36,7 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
-    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesetEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.
      *
@@ -151,6 +151,6 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
  * A file picked from a gallery. Its mime type lives in the gallery, so the
  * field carries only the path.
  */
-export declare function file(galleryModule: ValModule<Record<string, FilesEntryMetadata>>): FileSchema<GalleryFileSource>;
+export declare function file(galleryModule: ValModule<Record<string, FilesetEntryMetadata>>): FileSchema<GalleryFileSource>;
 /** A file of its own, carrying its own mime type. */
 export declare function file(options?: FileOptions): FileSchema<FileSource>;