@valbuild/shared 0.123.2 → 0.123.3

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @valbuild/shared
 
+## 0.123.3
+
+### Patch Changes
+
+- [#633](https://github.com/valbuild/val/pull/633) [`accf4f8`](https://github.com/valbuild/val/commit/accf4f852fe3400d762cc14e80316da741a69a9a) Thanks [@freekh](https://github.com/freekh)! - Stop `@valbuild/shared` replacing a consumer's own flexsearch types
+
+  `@valbuild/shared` gained a flexsearch dependency in 0.123.0, for
+  `search_content`, and typed its exported `SearchIndex.index` as flexsearch's
+  own `Index`. That put `import { Index } from "flexsearch"` into the published
+  `searchIndex.d.ts` — and flexsearch's type entry opens with
+  `declare module "flexsearch"`, which is an AMBIENT module declaration and so
+  global to a whole TypeScript program.
+
+  The effect on a project that uses flexsearch itself, at a different version:
+  its own calls are checked against the copy Val dragged in. valbuild/web pins
+  flexsearch 0.7 and builds an index with
+  `new flexsearch.Document({ language: "en", … })`; on `@valbuild/shared@0.123.2`
+  that stopped compiling, because 0.8's `DocumentOptions` has no `language`. Its
+  resolved copy was still 0.7 — only the types had been swapped underneath it.
+
+  `SearchIndex.index` is now a structural type covering the three methods this
+  package calls, so nothing in the published declarations names flexsearch. The
+  library is still used to build the index; that is a value import, which never
+  reaches a `.d.ts`.
+
+  No API change: `SearchIndex` is still assignable from a real flexsearch
+  `Index`, and `noFlexsearchInPublishedTypes.test.ts` asserts both halves of that
+  — that no source file names flexsearch in a type position, and that a real
+  `Index` still satisfies the stand-in, so it cannot drift from the library
+  unnoticed.
+
+- [#628](https://github.com/valbuild/val/pull/628) [`aef45ce`](https://github.com/valbuild/val/commit/aef45ce3ef269f1b6221de44a56df0f6a0d9dbbd) Thanks [@freekh](https://github.com/freekh)! - Stop the serialized-schema parser dropping schema metadata
+
+  `SerializedSchema` in `@valbuild/shared` is a zod mirror of the serialized
+  schema type, and its `z.object`s strip keys they do not declare. Five fields
+  were declared on some schemas and forgotten on others:
+
+  - `customValidate` — missing on twelve of the eighteen schemas. This is the flag
+    that says a schema declares a `.validate()`; the function itself cannot
+    serialize, so the flag is the only thing that tells the Studio to run the
+    custom validators against the real instance.
+  - `description` — missing on thirteen, so a `.describe()` went unseen.
+  - `remote` and `referencedModule` — missing on `s.image()` and `s.file()`, so a
+    remote field read as local and a gallery-backed field lost the gallery it
+    reads its dimensions and mime type from.
+  - the `message` on a `.regexp(pattern, message)` — so a field with a custom
+    pattern message fell back to the generic "Expected string to match reg
+    exp: …".
+
+  Because it strips rather than rejects, nothing failed and nothing said so. The
+  live `/schema` route was unaffected — `ValClient` validates the response and
+  then returns the raw JSON — but the history path consumes the parsed output, so
+  in a commit or historical patch-set view (`getModuleAtCommit`,
+  `getHistoricalPatchSet`) a schema's custom validators, description, remoteness
+  and backing gallery all quietly disappeared.
+
+  The fields every serialized schema shares are now spread from one
+  `commonSchemaFields` object instead of being retyped eighteen times, which is
+  how they drifted apart in the first place. A round-trip test walks each schema's
+  serialized output against the parsed result and fails with the path of any key
+  that did not survive, so a field added to a serialized schema and forgotten in
+  the parser is caught without anyone having to remember to assert it.
+
 ## 0.123.2
 
 ### Patch Changes

package/dist/declarations/src/internal/search/searchIndex.d.ts

@@ -1,5 +1,4 @@
 import { Json, ModuleFilePath, SerializedSchema, SourcePath } from "@valbuild/core";
-import { Index } from "flexsearch";
 /**
  * The search index and the labels to render for its hits.
  *
@@ -15,8 +14,37 @@ import { Index } from "flexsearch";
  * them — an agent and an editor searching the same project should find the same
  * things.
  */
+/**
+ * The parts of FlexSearch's `Index` this module uses.
+ *
+ * Structural, rather than importing flexsearch's own `Index`, because
+ * {@link SearchIndex} is EXPORTED — and a `.d.ts` that names `flexsearch` pulls
+ * that package's `declare module "flexsearch"` into every consumer's TypeScript
+ * program. Ambient module declarations are global to a program, so a consumer
+ * with its own flexsearch at another version then checks its OWN calls against
+ * the copy we dragged in, whichever of the two wins.
+ *
+ * That is not hypothetical: `@valbuild/shared` gained a flexsearch dependency
+ * in 0.123.0 for `search_content`, and valbuild/web — which pins flexsearch
+ * 0.7 and calls `new flexsearch.Document({ language: "en", … })` — stopped
+ * building on 0.123.2, because 0.8's `DocumentOptions` has no `language`. Its
+ * own resolved copy was still 0.7; only the types had been replaced.
+ *
+ * Three methods is all this module calls, and none of their signatures here is
+ * a guess: `add` and `remove` are used in `indexModule`/`removeModule`, and
+ * `search`'s result is only ever `.length`-ed, `.slice`-d and mapped over as
+ * ids. `FlexSearch.Index` is still constructed with the real library in
+ * {@link createSearchIndex} — a value import, which does not reach the `.d.ts`.
+ */
+type SearchableIndex = {
+    add(id: string, content: string): void;
+    remove(id: string): void;
+    search(query: string, options: {
+        limit: number;
+    }): (string | number)[];
+};
 export type SearchIndex = {
-    index: Index;
+    index: SearchableIndex;
     pathToLabel: Map<string, string>;
     /**
      * Which document ids belong to which module, so one module can be re-indexed
@@ -74,3 +102,4 @@ export type SearchResults = {
     totalIsLowerBound: boolean;
 };
 export declare function performSearch(searchIndex: SearchIndex | null, query: string, limit?: number, offset?: number): SearchResults;
+export {};

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -911,97 +911,96 @@ var InlineRender = zod.z.object({
   as: zod.z.literal("inline")
 });
 var FieldRender = InlineRender.optional();
-var SerializedStringSchema = zod.z.object({
-  type: zod.z.literal("string"),
+
+/**
+ * The fields EVERY serialized schema carries, in one place.
+ *
+ * Spread into each schema below rather than retyped, because retyping them is
+ * exactly how they went missing: `customValidate` and `description` were
+ * declared on six of the eighteen schemas and silently dropped by the other
+ * twelve. A field added to the base of `SerializedSchema` needs adding here and
+ * nowhere else.
+ *
+ * `type`, `opt` and whatever is particular to the schema stay at the call site
+ * - those differ per schema, so there is nothing to share.
+ */
+var commonSchemaFields = {
   render: FieldRender,
+  preview: zod.z.literal(true).optional(),
+  // Whether the schema declares a `.validate()`. The function cannot serialize,
+  // so this flag is what tells the Studio to run the custom validators on the
+  // main thread against the real instance - dropped, and they never run at all.
+  // See `hasCustomValidate` in `ui/spa/validation/customValidate.ts`.
+  customValidate: zod.z["boolean"]().optional(),
+  readonly: zod.z["boolean"]().optional(),
+  hidden: zod.z["boolean"]().optional(),
+  description: zod.z.string().optional()
+};
+var SerializedStringSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+  type: zod.z.literal("string"),
   // `.multiline()`. Stripped like any undeclared key if it goes missing here,
   // which is a single-line input where the author asked for a text box.
   multiline: zod.z["boolean"]().optional(),
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     maxLength: zod.z.number().optional(),
     minLength: zod.z.number().optional(),
     regexp: zod.z.object({
+      // `.regexp(re, message)`'s message. Written by
+      // `StringSchema.executeSerialize`, so omitting it here strips the
+      // author's own wording and leaves the generic "Expected string to
+      // match reg exp: …" in its place.
+      message: zod.z.string().optional(),
       source: zod.z.string(),
       flags: zod.z.string()
-    }).optional()
+    }).optional(),
+    customValidate: zod.z["boolean"]().optional()
   }).optional(),
   opt: zod.z["boolean"](),
-  raw: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedLiteralSchema = zod.z.object({
+  raw: zod.z["boolean"]()
+}));
+var SerializedLiteralSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("literal"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   value: zod.z.string(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedBooleanSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedBooleanSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("boolean"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedNumberSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedNumberSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("number"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     max: zod.z.number().optional(),
     min: zod.z.number().optional()
   }).optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var SerializedObjectSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("object"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     items: zod.z.record(zod.z.string(), SerializedSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedArraySchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("array"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     item: SerializedSchema,
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedUnionSchema = zod.z.lazy(function () {
-  return zod.z.union([zod.z.object({
+  return zod.z.union([zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("union"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     key: SerializedLiteralSchema,
     items: zod.z.array(SerializedLiteralSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  }), zod.z.object({
+    opt: zod.z["boolean"]()
+  })), zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("union"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     key: zod.z.string(),
     items: zod.z.array(SerializedObjectSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  })]);
+    opt: zod.z["boolean"]()
+  }))]);
 });
 var ImageEncodeOption = zod.z.union([zod.z.literal(false), zod.z.object({
   type: zod.z.literal("webp"),
@@ -1014,15 +1013,16 @@ var ImageOptions = zod.z.object({
   accept: zod.z.string().optional(),
   encode: ImageEncodeOption.optional()
 });
-var SerializedImageSchema = zod.z.object({
+var SerializedImageSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("image"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: ImageOptions.optional(),
   opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  // `.remote()`, and the gallery a gallery-backed field reads its metadata
+  // from. Neither is cosmetic: dropped, a remote field looks local and a
+  // gallery-backed one looks like it holds its own dimensions.
+  remote: zod.z["boolean"]().optional(),
+  referencedModule: zod.z.string().optional()
+}));
 var RichTextOptions = zod.z.lazy(function () {
   return zod.z.object({
     // Set by `.maxLength()` / `.minLength()`, not by the options argument.
@@ -1045,20 +1045,14 @@ var RichTextOptions = zod.z.lazy(function () {
     img: zod.z.union([zod.z["boolean"](), SerializedImageSchema]).optional()
   });
 });
-var SerializedRichTextSchema = zod.z.object({
+var SerializedRichTextSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("richtext"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: RichTextOptions.optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var SerializedRecordSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("record"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     item: SerializedSchema,
     opt: zod.z["boolean"](),
     // Optional gallery marker for files/images
@@ -1069,16 +1063,12 @@ var SerializedRecordSchema = zod.z.lazy(function () {
     remote: zod.z["boolean"]().optional(),
     encode: ImageEncodeOption.optional(),
     alt: SerializedSchema.optional(),
-    moduleMetadata: zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), zod.z.any())).optional(),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  }).passthrough();
+    moduleMetadata: zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), zod.z.any())).optional()
+  })).passthrough();
 });
 var SerializedKeyOfSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("keyOf"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     path: SourcePath,
     schema: zod.z.union([zod.z.object({
       type: zod.z.literal("object"),
@@ -1089,82 +1079,54 @@ var SerializedKeyOfSchema = zod.z.lazy(function () {
       opt: zod.z["boolean"]().optional()
     })]).optional(),
     values: zod.z.union([zod.z.literal("string"), zod.z.array(zod.z.string())]),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var FileOptions = zod.z.object({
   accept: zod.z.string().optional()
 });
-var SerializedFileSchema = zod.z.object({
+var SerializedFileSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("file"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: FileOptions.optional(),
   opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  // See `SerializedImageSchema` above: `.remote()` and the gallery a
+  // gallery-backed field reads from.
+  remote: zod.z["boolean"]().optional(),
+  referencedModule: zod.z.string().optional()
+}));
 var DateOptions = zod.z.object({
   from: zod.z.string().optional(),
   to: zod.z.string().optional()
 });
-var SerializedDateSchema = zod.z.object({
+var SerializedDateSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("date"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
-var SerializedDateTimeSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedDateTimeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("dateTime"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var ColorOptions = zod.z.object({
   format: zod.z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
   alpha: zod.z["boolean"]().optional()
 });
-var SerializedColorSchema = zod.z.object({
+var SerializedColorSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("color"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: ColorOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var CodeOptions = zod.z.object({
   language: zod.z["enum"](core.CODE_LANGUAGES).optional()
 });
-var SerializedCodeSchema = zod.z.object({
+var SerializedCodeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("code"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: CodeOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
-var SerializedRouteSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedRouteSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("route"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     include: zod.z.object({
       source: zod.z.string(),
@@ -1176,11 +1138,8 @@ var SerializedRouteSchema = zod.z.object({
     }).optional(),
     customValidate: zod.z["boolean"]().optional()
   }).optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 
 // A settings module, and each section inside one, serialize as this - the
 // shape is recursive because `items` holds sections which are themselves
@@ -1188,17 +1147,11 @@ var SerializedRouteSchema = zod.z.object({
 // (see core/src/schema/settings.ts), but they are accepted here because they
 // are part of the declared type.
 var SerializedSettingsSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("settings"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     items: zod.z.record(zod.z.string(), SerializedSchema),
-    opt: zod.z["boolean"](),
-    customValidate: zod.z["boolean"]().optional(),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional(),
-    description: zod.z.string().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
@@ -5329,6 +5282,28 @@ function getRefParts(ref) {
  * them — an agent and an editor searching the same project should find the same
  * things.
  */
+/**
+ * The parts of FlexSearch's `Index` this module uses.
+ *
+ * Structural, rather than importing flexsearch's own `Index`, because
+ * {@link SearchIndex} is EXPORTED — and a `.d.ts` that names `flexsearch` pulls
+ * that package's `declare module "flexsearch"` into every consumer's TypeScript
+ * program. Ambient module declarations are global to a program, so a consumer
+ * with its own flexsearch at another version then checks its OWN calls against
+ * the copy we dragged in, whichever of the two wins.
+ *
+ * That is not hypothetical: `@valbuild/shared` gained a flexsearch dependency
+ * in 0.123.0 for `search_content`, and valbuild/web — which pins flexsearch
+ * 0.7 and calls `new flexsearch.Document({ language: "en", … })` — stopped
+ * building on 0.123.2, because 0.8's `DocumentOptions` has no `language`. Its
+ * own resolved copy was still 0.7; only the types had been replaced.
+ *
+ * Three methods is all this module calls, and none of their signatures here is
+ * a guess: `add` and `remove` are used in `indexModule`/`removeModule`, and
+ * `search`'s result is only ever `.length`-ed, `.slice`-d and mapped over as
+ * ids. `FlexSearch.Index` is still constructed with the real library in
+ * {@link createSearchIndex} — a value import, which does not reach the `.d.ts`.
+ */
 
 /** An index with nothing in it. Fill it with {@link indexModule}. */
 function createSearchIndex() {
@@ -5430,9 +5405,9 @@ function removeModule(searchIndex, moduleFilePath) {
     _step;
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var id = _step.value;
-      index.remove(id);
-      pathToLabel["delete"](id);
+      var _id = _step.value;
+      index.remove(_id);
+      pathToLabel["delete"](_id);
     }
   } catch (err) {
     _iterator.e(err);

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -911,97 +911,96 @@ var InlineRender = zod.z.object({
   as: zod.z.literal("inline")
 });
 var FieldRender = InlineRender.optional();
-var SerializedStringSchema = zod.z.object({
-  type: zod.z.literal("string"),
+
+/**
+ * The fields EVERY serialized schema carries, in one place.
+ *
+ * Spread into each schema below rather than retyped, because retyping them is
+ * exactly how they went missing: `customValidate` and `description` were
+ * declared on six of the eighteen schemas and silently dropped by the other
+ * twelve. A field added to the base of `SerializedSchema` needs adding here and
+ * nowhere else.
+ *
+ * `type`, `opt` and whatever is particular to the schema stay at the call site
+ * - those differ per schema, so there is nothing to share.
+ */
+var commonSchemaFields = {
   render: FieldRender,
+  preview: zod.z.literal(true).optional(),
+  // Whether the schema declares a `.validate()`. The function cannot serialize,
+  // so this flag is what tells the Studio to run the custom validators on the
+  // main thread against the real instance - dropped, and they never run at all.
+  // See `hasCustomValidate` in `ui/spa/validation/customValidate.ts`.
+  customValidate: zod.z["boolean"]().optional(),
+  readonly: zod.z["boolean"]().optional(),
+  hidden: zod.z["boolean"]().optional(),
+  description: zod.z.string().optional()
+};
+var SerializedStringSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+  type: zod.z.literal("string"),
   // `.multiline()`. Stripped like any undeclared key if it goes missing here,
   // which is a single-line input where the author asked for a text box.
   multiline: zod.z["boolean"]().optional(),
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     maxLength: zod.z.number().optional(),
     minLength: zod.z.number().optional(),
     regexp: zod.z.object({
+      // `.regexp(re, message)`'s message. Written by
+      // `StringSchema.executeSerialize`, so omitting it here strips the
+      // author's own wording and leaves the generic "Expected string to
+      // match reg exp: …" in its place.
+      message: zod.z.string().optional(),
       source: zod.z.string(),
       flags: zod.z.string()
-    }).optional()
+    }).optional(),
+    customValidate: zod.z["boolean"]().optional()
   }).optional(),
   opt: zod.z["boolean"](),
-  raw: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedLiteralSchema = zod.z.object({
+  raw: zod.z["boolean"]()
+}));
+var SerializedLiteralSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("literal"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   value: zod.z.string(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedBooleanSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedBooleanSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("boolean"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
-var SerializedNumberSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedNumberSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("number"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     max: zod.z.number().optional(),
     min: zod.z.number().optional()
   }).optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var SerializedObjectSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("object"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     items: zod.z.record(zod.z.string(), SerializedSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedArraySchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("array"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     item: SerializedSchema,
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedUnionSchema = zod.z.lazy(function () {
-  return zod.z.union([zod.z.object({
+  return zod.z.union([zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("union"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     key: SerializedLiteralSchema,
     items: zod.z.array(SerializedLiteralSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  }), zod.z.object({
+    opt: zod.z["boolean"]()
+  })), zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("union"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     key: zod.z.string(),
     items: zod.z.array(SerializedObjectSchema),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  })]);
+    opt: zod.z["boolean"]()
+  }))]);
 });
 var ImageEncodeOption = zod.z.union([zod.z.literal(false), zod.z.object({
   type: zod.z.literal("webp"),
@@ -1014,15 +1013,16 @@ var ImageOptions = zod.z.object({
   accept: zod.z.string().optional(),
   encode: ImageEncodeOption.optional()
 });
-var SerializedImageSchema = zod.z.object({
+var SerializedImageSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("image"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: ImageOptions.optional(),
   opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  // `.remote()`, and the gallery a gallery-backed field reads its metadata
+  // from. Neither is cosmetic: dropped, a remote field looks local and a
+  // gallery-backed one looks like it holds its own dimensions.
+  remote: zod.z["boolean"]().optional(),
+  referencedModule: zod.z.string().optional()
+}));
 var RichTextOptions = zod.z.lazy(function () {
   return zod.z.object({
     // Set by `.maxLength()` / `.minLength()`, not by the options argument.
@@ -1045,20 +1045,14 @@ var RichTextOptions = zod.z.lazy(function () {
     img: zod.z.union([zod.z["boolean"](), SerializedImageSchema]).optional()
   });
 });
-var SerializedRichTextSchema = zod.z.object({
+var SerializedRichTextSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("richtext"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: RichTextOptions.optional(),
-  opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var SerializedRecordSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("record"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     item: SerializedSchema,
     opt: zod.z["boolean"](),
     // Optional gallery marker for files/images
@@ -1069,16 +1063,12 @@ var SerializedRecordSchema = zod.z.lazy(function () {
     remote: zod.z["boolean"]().optional(),
     encode: ImageEncodeOption.optional(),
     alt: SerializedSchema.optional(),
-    moduleMetadata: zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), zod.z.any())).optional(),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  }).passthrough();
+    moduleMetadata: zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), zod.z.any())).optional()
+  })).passthrough();
 });
 var SerializedKeyOfSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("keyOf"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     path: SourcePath,
     schema: zod.z.union([zod.z.object({
       type: zod.z.literal("object"),
@@ -1089,82 +1079,54 @@ var SerializedKeyOfSchema = zod.z.lazy(function () {
       opt: zod.z["boolean"]().optional()
     })]).optional(),
     values: zod.z.union([zod.z.literal("string"), zod.z.array(zod.z.string())]),
-    opt: zod.z["boolean"](),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var FileOptions = zod.z.object({
   accept: zod.z.string().optional()
 });
-var SerializedFileSchema = zod.z.object({
+var SerializedFileSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("file"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: FileOptions.optional(),
   opt: zod.z["boolean"](),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  // See `SerializedImageSchema` above: `.remote()` and the gallery a
+  // gallery-backed field reads from.
+  remote: zod.z["boolean"]().optional(),
+  referencedModule: zod.z.string().optional()
+}));
 var DateOptions = zod.z.object({
   from: zod.z.string().optional(),
   to: zod.z.string().optional()
 });
-var SerializedDateSchema = zod.z.object({
+var SerializedDateSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("date"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
-var SerializedDateTimeSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedDateTimeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("dateTime"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var ColorOptions = zod.z.object({
   format: zod.z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
   alpha: zod.z["boolean"]().optional()
 });
-var SerializedColorSchema = zod.z.object({
+var SerializedColorSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("color"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: ColorOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 var CodeOptions = zod.z.object({
   language: zod.z["enum"](core.CODE_LANGUAGES).optional()
 });
-var SerializedCodeSchema = zod.z.object({
+var SerializedCodeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("code"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: CodeOptions.optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional(),
-  description: zod.z.string().optional()
-});
-var SerializedRouteSchema = zod.z.object({
+  opt: zod.z["boolean"]()
+}));
+var SerializedRouteSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
   type: zod.z.literal("route"),
-  render: FieldRender,
-  preview: zod.z.literal(true).optional(),
   options: zod.z.object({
     include: zod.z.object({
       source: zod.z.string(),
@@ -1176,11 +1138,8 @@ var SerializedRouteSchema = zod.z.object({
     }).optional(),
     customValidate: zod.z["boolean"]().optional()
   }).optional(),
-  opt: zod.z["boolean"](),
-  customValidate: zod.z["boolean"]().optional(),
-  readonly: zod.z["boolean"]().optional(),
-  hidden: zod.z["boolean"]().optional()
-});
+  opt: zod.z["boolean"]()
+}));
 
 // A settings module, and each section inside one, serialize as this - the
 // shape is recursive because `items` holds sections which are themselves
@@ -1188,17 +1147,11 @@ var SerializedRouteSchema = zod.z.object({
 // (see core/src/schema/settings.ts), but they are accepted here because they
 // are part of the declared type.
 var SerializedSettingsSchema = zod.z.lazy(function () {
-  return zod.z.object({
+  return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
     type: zod.z.literal("settings"),
-    render: FieldRender,
-    preview: zod.z.literal(true).optional(),
     items: zod.z.record(zod.z.string(), SerializedSchema),
-    opt: zod.z["boolean"](),
-    customValidate: zod.z["boolean"]().optional(),
-    readonly: zod.z["boolean"]().optional(),
-    hidden: zod.z["boolean"]().optional(),
-    description: zod.z.string().optional()
-  });
+    opt: zod.z["boolean"]()
+  }));
 });
 var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
@@ -5329,6 +5282,28 @@ function getRefParts(ref) {
  * them — an agent and an editor searching the same project should find the same
  * things.
  */
+/**
+ * The parts of FlexSearch's `Index` this module uses.
+ *
+ * Structural, rather than importing flexsearch's own `Index`, because
+ * {@link SearchIndex} is EXPORTED — and a `.d.ts` that names `flexsearch` pulls
+ * that package's `declare module "flexsearch"` into every consumer's TypeScript
+ * program. Ambient module declarations are global to a program, so a consumer
+ * with its own flexsearch at another version then checks its OWN calls against
+ * the copy we dragged in, whichever of the two wins.
+ *
+ * That is not hypothetical: `@valbuild/shared` gained a flexsearch dependency
+ * in 0.123.0 for `search_content`, and valbuild/web — which pins flexsearch
+ * 0.7 and calls `new flexsearch.Document({ language: "en", … })` — stopped
+ * building on 0.123.2, because 0.8's `DocumentOptions` has no `language`. Its
+ * own resolved copy was still 0.7; only the types had been replaced.
+ *
+ * Three methods is all this module calls, and none of their signatures here is
+ * a guess: `add` and `remove` are used in `indexModule`/`removeModule`, and
+ * `search`'s result is only ever `.length`-ed, `.slice`-d and mapped over as
+ * ids. `FlexSearch.Index` is still constructed with the real library in
+ * {@link createSearchIndex} — a value import, which does not reach the `.d.ts`.
+ */
 
 /** An index with nothing in it. Fill it with {@link indexModule}. */
 function createSearchIndex() {
@@ -5430,9 +5405,9 @@ function removeModule(searchIndex, moduleFilePath) {
     _step;
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var id = _step.value;
-      index.remove(id);
-      pathToLabel["delete"](id);
+      var _id = _step.value;
+      index.remove(_id);
+      pathToLabel["delete"](_id);
     }
   } catch (err) {
     _iterator.e(err);

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

@@ -904,97 +904,96 @@ var InlineRender = z.object({
   as: z.literal("inline")
 });
 var FieldRender = InlineRender.optional();
-var SerializedStringSchema = z.object({
-  type: z.literal("string"),
+
+/**
+ * The fields EVERY serialized schema carries, in one place.
+ *
+ * Spread into each schema below rather than retyped, because retyping them is
+ * exactly how they went missing: `customValidate` and `description` were
+ * declared on six of the eighteen schemas and silently dropped by the other
+ * twelve. A field added to the base of `SerializedSchema` needs adding here and
+ * nowhere else.
+ *
+ * `type`, `opt` and whatever is particular to the schema stay at the call site
+ * - those differ per schema, so there is nothing to share.
+ */
+var commonSchemaFields = {
   render: FieldRender,
+  preview: z.literal(true).optional(),
+  // Whether the schema declares a `.validate()`. The function cannot serialize,
+  // so this flag is what tells the Studio to run the custom validators on the
+  // main thread against the real instance - dropped, and they never run at all.
+  // See `hasCustomValidate` in `ui/spa/validation/customValidate.ts`.
+  customValidate: z["boolean"]().optional(),
+  readonly: z["boolean"]().optional(),
+  hidden: z["boolean"]().optional(),
+  description: z.string().optional()
+};
+var SerializedStringSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+  type: z.literal("string"),
   // `.multiline()`. Stripped like any undeclared key if it goes missing here,
   // which is a single-line input where the author asked for a text box.
   multiline: z["boolean"]().optional(),
-  preview: z.literal(true).optional(),
   options: z.object({
     maxLength: z.number().optional(),
     minLength: z.number().optional(),
     regexp: z.object({
+      // `.regexp(re, message)`'s message. Written by
+      // `StringSchema.executeSerialize`, so omitting it here strips the
+      // author's own wording and leaves the generic "Expected string to
+      // match reg exp: …" in its place.
+      message: z.string().optional(),
       source: z.string(),
       flags: z.string()
-    }).optional()
+    }).optional(),
+    customValidate: z["boolean"]().optional()
   }).optional(),
   opt: z["boolean"](),
-  raw: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
-var SerializedLiteralSchema = z.object({
+  raw: z["boolean"]()
+}));
+var SerializedLiteralSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("literal"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   value: z.string(),
-  opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
-var SerializedBooleanSchema = z.object({
+  opt: z["boolean"]()
+}));
+var SerializedBooleanSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("boolean"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
-  opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
-var SerializedNumberSchema = z.object({
+  opt: z["boolean"]()
+}));
+var SerializedNumberSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("number"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: z.object({
     max: z.number().optional(),
     min: z.number().optional()
   }).optional(),
-  opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
+  opt: z["boolean"]()
+}));
 var SerializedObjectSchema = z.lazy(function () {
-  return z.object({
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("object"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     items: z.record(z.string(), SerializedSchema),
-    opt: z["boolean"](),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  });
+    opt: z["boolean"]()
+  }));
 });
 var SerializedArraySchema = z.lazy(function () {
-  return z.object({
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("array"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     item: SerializedSchema,
-    opt: z["boolean"](),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  });
+    opt: z["boolean"]()
+  }));
 });
 var SerializedUnionSchema = z.lazy(function () {
-  return z.union([z.object({
+  return z.union([z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("union"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     key: SerializedLiteralSchema,
     items: z.array(SerializedLiteralSchema),
-    opt: z["boolean"](),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  }), z.object({
+    opt: z["boolean"]()
+  })), z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("union"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     key: z.string(),
     items: z.array(SerializedObjectSchema),
-    opt: z["boolean"](),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  })]);
+    opt: z["boolean"]()
+  }))]);
 });
 var ImageEncodeOption = z.union([z.literal(false), z.object({
   type: z.literal("webp"),
@@ -1007,15 +1006,16 @@ var ImageOptions = z.object({
   accept: z.string().optional(),
   encode: ImageEncodeOption.optional()
 });
-var SerializedImageSchema = z.object({
+var SerializedImageSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("image"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: ImageOptions.optional(),
   opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
+  // `.remote()`, and the gallery a gallery-backed field reads its metadata
+  // from. Neither is cosmetic: dropped, a remote field looks local and a
+  // gallery-backed one looks like it holds its own dimensions.
+  remote: z["boolean"]().optional(),
+  referencedModule: z.string().optional()
+}));
 var RichTextOptions = z.lazy(function () {
   return z.object({
     // Set by `.maxLength()` / `.minLength()`, not by the options argument.
@@ -1038,20 +1038,14 @@ var RichTextOptions = z.lazy(function () {
     img: z.union([z["boolean"](), SerializedImageSchema]).optional()
   });
 });
-var SerializedRichTextSchema = z.object({
+var SerializedRichTextSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("richtext"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: RichTextOptions.optional(),
-  opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
+  opt: z["boolean"]()
+}));
 var SerializedRecordSchema = z.lazy(function () {
-  return z.object({
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("record"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     item: SerializedSchema,
     opt: z["boolean"](),
     // Optional gallery marker for files/images
@@ -1062,16 +1056,12 @@ var SerializedRecordSchema = z.lazy(function () {
     remote: z["boolean"]().optional(),
     encode: ImageEncodeOption.optional(),
     alt: SerializedSchema.optional(),
-    moduleMetadata: z.record(z.string(), z.record(z.string(), z.any())).optional(),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  }).passthrough();
+    moduleMetadata: z.record(z.string(), z.record(z.string(), z.any())).optional()
+  })).passthrough();
 });
 var SerializedKeyOfSchema = z.lazy(function () {
-  return z.object({
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("keyOf"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     path: SourcePath,
     schema: z.union([z.object({
       type: z.literal("object"),
@@ -1082,82 +1072,54 @@ var SerializedKeyOfSchema = z.lazy(function () {
       opt: z["boolean"]().optional()
     })]).optional(),
     values: z.union([z.literal("string"), z.array(z.string())]),
-    opt: z["boolean"](),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional()
-  });
+    opt: z["boolean"]()
+  }));
 });
 var FileOptions = z.object({
   accept: z.string().optional()
 });
-var SerializedFileSchema = z.object({
+var SerializedFileSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("file"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: FileOptions.optional(),
   opt: z["boolean"](),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
+  // See `SerializedImageSchema` above: `.remote()` and the gallery a
+  // gallery-backed field reads from.
+  remote: z["boolean"]().optional(),
+  referencedModule: z.string().optional()
+}));
 var DateOptions = z.object({
   from: z.string().optional(),
   to: z.string().optional()
 });
-var SerializedDateSchema = z.object({
+var SerializedDateSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("date"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: z["boolean"](),
-  customValidate: z["boolean"]().optional(),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional(),
-  description: z.string().optional()
-});
-var SerializedDateTimeSchema = z.object({
+  opt: z["boolean"]()
+}));
+var SerializedDateTimeSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("dateTime"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: DateOptions.optional(),
-  opt: z["boolean"](),
-  customValidate: z["boolean"]().optional(),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional(),
-  description: z.string().optional()
-});
+  opt: z["boolean"]()
+}));
 var ColorOptions = z.object({
   format: z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
   alpha: z["boolean"]().optional()
 });
-var SerializedColorSchema = z.object({
+var SerializedColorSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("color"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: ColorOptions.optional(),
-  opt: z["boolean"](),
-  customValidate: z["boolean"]().optional(),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional(),
-  description: z.string().optional()
-});
+  opt: z["boolean"]()
+}));
 var CodeOptions = z.object({
   language: z["enum"](CODE_LANGUAGES).optional()
 });
-var SerializedCodeSchema = z.object({
+var SerializedCodeSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("code"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: CodeOptions.optional(),
-  opt: z["boolean"](),
-  customValidate: z["boolean"]().optional(),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional(),
-  description: z.string().optional()
-});
-var SerializedRouteSchema = z.object({
+  opt: z["boolean"]()
+}));
+var SerializedRouteSchema = z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
   type: z.literal("route"),
-  render: FieldRender,
-  preview: z.literal(true).optional(),
   options: z.object({
     include: z.object({
       source: z.string(),
@@ -1169,11 +1131,8 @@ var SerializedRouteSchema = z.object({
     }).optional(),
     customValidate: z["boolean"]().optional()
   }).optional(),
-  opt: z["boolean"](),
-  customValidate: z["boolean"]().optional(),
-  readonly: z["boolean"]().optional(),
-  hidden: z["boolean"]().optional()
-});
+  opt: z["boolean"]()
+}));
 
 // A settings module, and each section inside one, serialize as this - the
 // shape is recursive because `items` holds sections which are themselves
@@ -1181,17 +1140,11 @@ var SerializedRouteSchema = z.object({
 // (see core/src/schema/settings.ts), but they are accepted here because they
 // are part of the declared type.
 var SerializedSettingsSchema = z.lazy(function () {
-  return z.object({
+  return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
     type: z.literal("settings"),
-    render: FieldRender,
-    preview: z.literal(true).optional(),
     items: z.record(z.string(), SerializedSchema),
-    opt: z["boolean"](),
-    customValidate: z["boolean"]().optional(),
-    readonly: z["boolean"]().optional(),
-    hidden: z["boolean"]().optional(),
-    description: z.string().optional()
-  });
+    opt: z["boolean"]()
+  }));
 });
 var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
@@ -5322,6 +5275,28 @@ function getRefParts(ref) {
  * them — an agent and an editor searching the same project should find the same
  * things.
  */
+/**
+ * The parts of FlexSearch's `Index` this module uses.
+ *
+ * Structural, rather than importing flexsearch's own `Index`, because
+ * {@link SearchIndex} is EXPORTED — and a `.d.ts` that names `flexsearch` pulls
+ * that package's `declare module "flexsearch"` into every consumer's TypeScript
+ * program. Ambient module declarations are global to a program, so a consumer
+ * with its own flexsearch at another version then checks its OWN calls against
+ * the copy we dragged in, whichever of the two wins.
+ *
+ * That is not hypothetical: `@valbuild/shared` gained a flexsearch dependency
+ * in 0.123.0 for `search_content`, and valbuild/web — which pins flexsearch
+ * 0.7 and calls `new flexsearch.Document({ language: "en", … })` — stopped
+ * building on 0.123.2, because 0.8's `DocumentOptions` has no `language`. Its
+ * own resolved copy was still 0.7; only the types had been replaced.
+ *
+ * Three methods is all this module calls, and none of their signatures here is
+ * a guess: `add` and `remove` are used in `indexModule`/`removeModule`, and
+ * `search`'s result is only ever `.length`-ed, `.slice`-d and mapped over as
+ * ids. `FlexSearch.Index` is still constructed with the real library in
+ * {@link createSearchIndex} — a value import, which does not reach the `.d.ts`.
+ */
 
 /** An index with nothing in it. Fill it with {@link indexModule}. */
 function createSearchIndex() {
@@ -5423,9 +5398,9 @@ function removeModule(searchIndex, moduleFilePath) {
     _step;
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var id = _step.value;
-      index.remove(id);
-      pathToLabel["delete"](id);
+      var _id = _step.value;
+      index.remove(_id);
+      pathToLabel["delete"](_id);
     }
   } catch (err) {
     _iterator.e(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.123.2",
+  "version": "0.123.3",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {