@valbuild/core 0.120.0 → 0.124.0

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # @valbuild/core
 
+## 0.124.0
+
+### Minor Changes
+
+- [#622](https://github.com/valbuild/val/pull/622) [`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.images()` and `s.files()` no longer take a `remote` option. Use
+  `.remote()`, the same way `s.image()` and `s.file()` already did.
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images", remote: true });
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+    remote: true,
+  });
+
+  // after
+  s.images({ directory: "/public/val/images" }).remote();
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+  }).remote();
+  ```
+
+  Behaviour is unchanged — remote is still off unless asked for. This only makes
+  remote one thing spelled one way across all four media schemas, instead of an
+  option on the two collections and a method on the two fields. `remote: false`
+  has no replacement because it was the default; drop it.
+
+## 0.121.0
+
+### Minor Changes
+
+- [#605](https://github.com/valbuild/val/pull/605) [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79) Thanks [@freekh](https://github.com/freekh)! - `s.settings()`: the project's settings, as content.
+
+  A settings module is one per project, at the root of the content tree:
+
+  ```typescript
+  // settings.val.ts
+  export default c.define("/settings.val.ts", s.settings(), {});
+  ```
+
+  Register it in `val.modules.ts` like any other module, and it shows up in the
+  Studio under the cog at the foot of the left rail. Everything in it is content:
+  it is edited as a draft, it appears in the publish diff, and it is the same for
+  everyone working on the project.
+
+  Every key is optional, at every level, so `{}` is a complete settings module —
+  and stays one as sections are added. What it holds today is the assistant:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    assistant: {
+      enabled: true,
+      context: "A CMS for developers, run by a team of four in Oslo.",
+      tone: "Plain and direct. British English, sentence case in headings.",
+    },
+  });
+  ```
+
+  `context` is background the assistant would otherwise guess at; `tone` is how it
+  should write when it writes content. Both are sent with every message it makes.
+
+  `enabled` decides whether editors have an assistant, and it has **three** states
+  rather than two:
+
+  - `true` — they do.
+  - `false` — they do not, and every trace of it goes: no button in the top bar,
+    no row in the quick actions, no panel, nothing sent.
+  - unset — nobody has decided. The assistant is still **shown**, and asks to be
+    turned on before it is used. Hiding an assistant nobody has decided about
+    means nobody discovers it; quietly enabling one means a project starts sending
+    its content to a model because it did not know to say no.
+
+  A project with no settings module at all has an assistant, as before: there is
+  nowhere to record a decision, and nowhere for the prompt to write the answer.
+
+  **Breaking: `ai.chat` is gone from `val.config.ts`.** Whether the assistant is
+  available is a decision about the project's content, made by the people who edit
+  it, so it moved to settings — turning the chat on used to take a developer, a
+  deploy and a code review of a boolean. Remove the whole block:
+
+  ```diff
+   const { s, c, val, config } = initVal({
+  -  ai: {
+  -    chat: {
+  -      experimental: { enable: true },
+  -      suggestions: ["Summarize", "Fix typos at this page"],
+  -      title: "Ask me anything",
+  -      description: "Val can answer questions about the content.",
+  -    },
+  -  },
+   });
+  ```
+
+  `experimental.enable` becomes `assistant.enabled` in the settings module.
+  `suggestions`, `title` and `description` are removed with nothing replacing
+  them: the assistant now opens with its own copy. A project that had the chat
+  enabled and wants it to stay on for everyone should write
+  `assistant: { enabled: true }` — otherwise editors are offered it and asked.
+
+  `ai.commitMessages` stays in `val.config.ts`, and is unaffected.
+
+  Two settings modules, or one in a subdirectory, is a module error: the dev
+  server refuses to serve sources, `npx val validate` reports it against the file,
+  and the Studio says so rather than picking one.
+
+### Patch Changes
+
+- [#607](https://github.com/valbuild/val/pull/607) [`2bcbee1`](https://github.com/valbuild/val/commit/2bcbee1be682c2bbd5b7bc7d152ddd4204162fd2) Thanks [@freekh](https://github.com/freekh)! - `.readonly()` and `.hidden()` now take the flag as an argument, so a schema can
+  decide these from a variable instead of only from whether the call was written at
+  all:
+
+  ```ts
+  s.string().readonly(!canEdit);
+  s.image().hidden(hideMedia);
+  ```
+
+  The argument defaults to `true`, so `.readonly()` and `.readonly(true)` are the
+  same thing and nothing about existing schemas changes. Passing `false` leaves the
+  field editable or visible, which is also what a schema is without the call - it
+  is there so the flag can come from a variable.
+
 ## 0.120.0
 
 ### Minor Changes

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

@@ -3,13 +3,14 @@ export { modules, type ValModules } from "./modules.js";
 export { extractValModules, computeValModuleShas, type ExtractedValModules, type ValModuleShaEntry, type ValModuleShas, type ExtractedModuleError, } from "./extractValModules.js";
 export type { InitVal, ValConfig, ValConstructor, ContentConstructor, } from "./initVal.js";
 export { Schema, type SerializedSchema, type SelectorOfSchema } from "./schema/index.js";
-export { hasRemoteFileSchema } from "./schema/hasRemoteFileSchema.js";
+export { hasRemoteFileSchema, hasMediaSchema, } from "./schema/hasRemoteFileSchema.js";
 export type { ImageMetadata, ImageEncodeOption, ImageEncodeOptions, } from "./schema/image.js";
 export type { FileMetadata } from "./schema/file.js";
 export type { ValModule, SerializedModule, InferValModuleType } from "./module.js";
 export type { SourceObject, SourcePrimitive, Source } from "./source/index.js";
 export type { FileSource } from "./source/media.js";
 export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
+export type { ExternalRecordSrc, ExternalRecordWritableSrc, ExternalItemOf, ExternalLabelOf, ExternalReadonlyOf, } from "./source/external.js";
 export type { RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
@@ -35,6 +36,8 @@ import { getMimeType, mimeTypeToFileExt, filenameToMimeType, mimeTypeMatchesAcce
 import { type ImageMetadata } from "./schema/image.js";
 import { type FileMetadata } from "./schema/file.js";
 import { isJson, getJsonImport, resolveJsonValues } from "./source/json.js";
+import { isExternal, hasInlineExternalEntries } from "./source/external.js";
+import { createExternalFileRef, splitExternalFileRef, isExternalFileRef } from "./source/externalRef.js";
 import { createRemoteRef } from "./source/remote.js";
 import { getValidationBasis, getValidationHash } from "./remote/validationBasis.js";
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
@@ -50,6 +53,9 @@ export { type SerializedBooleanSchema, BooleanSchema } from "./schema/boolean.js
 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 ResolvedSettingsModule, SETTINGS_MODULE_CONVENTION, isRootModuleFilePath, resolveSettingsModule, } from "./settingsModule.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";
@@ -108,6 +114,11 @@ declare const Internal: {
     isJson: typeof isJson;
     getJsonImport: typeof getJsonImport;
     resolveJsonValues: typeof resolveJsonValues;
+    isExternal: typeof isExternal;
+    hasInlineExternalEntries: typeof hasInlineExternalEntries;
+    createExternalFileRef: typeof createExternalFileRef;
+    splitExternalFileRef: typeof splitExternalFileRef;
+    isExternalFileRef: typeof isExternalFileRef;
     createValPathOfItem: typeof createValPathOfItem;
     getSHA256Hash: (bits: Uint8Array) => string;
     initSchema: typeof initSchema;

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

@@ -18,6 +18,7 @@ import { color } from "./schema/color.js";
 import { route } from "./schema/route.js";
 import { router } from "./schema/router.js";
 import { images } from "./schema/images.js";
+import { settings } from "./schema/settings.js";
 export type InitSchema = {
     /**
      * Define a string.
@@ -299,6 +300,31 @@ export type InitSchema = {
      * ```
      */
     readonly files: typeof files;
+    /**
+     * Define the project's settings.
+     *
+     * One per project, at the root of the content tree — a module file path with
+     * no directory segment, `/settings.val.ts` by convention. Every section is
+     * optional, so `{}` is a complete settings module and stays one as sections
+     * are added.
+     *
+     * @example
+     * ```typescript
+     * export default c.define("/settings.val.ts", s.settings(), {});
+     * ```
+     *
+     * @example
+     * ```typescript
+     * export default c.define("/settings.val.ts", s.settings(), {
+     *   assistant: {
+     *     enabled: true,
+     *     context: "A CMS for developers. British English throughout.",
+     *     tone: "Plain and direct. Sentence case in headings.",
+     *   },
+     * });
+     * ```
+     */
+    readonly settings: typeof settings;
 };
 export declare function initSchema(): {
     string: <T extends string>(options?: Record<string, never>) => import("./index.js").StringSchema<T>;
@@ -349,4 +375,5 @@ export declare function initSchema(): {
         mimeType: string;
         alt: string | null;
     }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/images.js").ImagesEntryMetadata>>;
+    settings: typeof settings;
 };

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

@@ -2,9 +2,11 @@ import { define } from "./module.js";
 import { InitSchema } from "./initSchema.js";
 import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
+import { external } from "./source/external.js";
 export type ContentConstructor = {
     define: typeof define;
     json: typeof json;
+    external: typeof external;
 };
 export type ValConstructor = {
     unstable_getPath: typeof getPath;
@@ -20,17 +22,20 @@ export type ValConfig = {
     gitBranch?: string;
     defaultTheme?: "dark" | "light";
     ai?: {
+        /**
+         * The AI commit-message summariser.
+         *
+         * Still config, and deliberately: it is about how the repository is
+         * written to rather than about the content, and it is getting settings of
+         * its own. The ASSISTANT is not here — it is `s.settings()`, under
+         * `assistant.enabled`, because whether editors have a chat is a decision
+         * about the
+         * project's content, made by the people who edit it, and published like any
+         * other content change.
+         */
         commitMessages?: {
             disabled?: boolean;
         };
-        chat?: {
-            experimental?: {
-                enable?: boolean;
-            };
-            suggestions?: string[];
-            title?: string;
-            description?: string;
-        };
     };
 };
 export type InitVal = {

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

@@ -1,6 +1,7 @@
 import { Schema, SelectorOfSchema, SerializedSchema } from "./schema/index.js";
 import { GenericSelector, SelectorOf, SelectorSource } from "./selector/index.js";
 import { Source } from "./source/index.js";
+import { ExternalRecordSrc } from "./source/external.js";
 import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
@@ -15,8 +16,24 @@ export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSourc
 } ? {
     [key in keyof T]: ReplaceRawStringWithString<T[key]>;
 } : T extends SelectorSource[] ? ReplaceRawStringWithString<T[number]>[] : T;
+/**
+ * What may be WRITTEN as an external record's source, on top of the marker.
+ *
+ * Entries inline in the `.val.ts` are accepted on purpose — the same call
+ * `.jsonValues()` makes for the same reason: pasting content straight into the
+ * module is the natural first thing to write, and a type error there is a dead
+ * end, because the author cannot see what to write instead. Validation reports
+ * them as an `external:upload` fix, and they are readable at runtime meanwhile.
+ *
+ * Widened HERE rather than in the schema's own source type so that the MODULE
+ * stays typed on the marker alone. An adapter is bound to a module, and a module
+ * whose type were "marker or plain record" would be indistinguishable from an
+ * ordinary record — which would let `entry()` accept a module that is not
+ * external at all.
+ */
+type InlineEntriesFor<S> = S extends ExternalRecordSrc<infer Item, string, boolean> ? Record<string, Item> : never;
 export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
-schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
+schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>> | InlineEntriesFor<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
 /**
  * Whether `value` is a Val module, i.e. something {@link define} produced.

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

@@ -43,8 +43,8 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ArraySchema<T, Src | null>;
-    readonly(): ArraySchema<T, Src>;
-    hidden(): ArraySchema<T, Src>;
+    readonly(isReadonly?: boolean): ArraySchema<T, Src>;
+    hidden(isHidden?: boolean): ArraySchema<T, Src>;
     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/boolean.d.ts

@@ -29,8 +29,8 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): BooleanSchema<Src | null>;
-    readonly(): BooleanSchema<Src>;
-    hidden(): BooleanSchema<Src>;
+    readonly(isReadonly?: boolean): BooleanSchema<Src>;
+    hidden(isHidden?: boolean): BooleanSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -61,8 +61,8 @@ export declare class CodeSchema<Src extends string | null> extends Schema<Src> {
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): CodeSchema<Src | null>;
-    readonly(): CodeSchema<Src>;
-    hidden(): CodeSchema<Src>;
+    readonly(isReadonly?: boolean): CodeSchema<Src>;
+    hidden(isHidden?: boolean): CodeSchema<Src>;
     /**
      * How this field is laid out in the editor when it is the item of an array
      * or record: `{ as: "inline" }` renders the field itself inside each row,

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

@@ -56,8 +56,8 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ColorSchema<Src | null>;
-    readonly(): ColorSchema<Src>;
-    hidden(): ColorSchema<Src>;
+    readonly(isReadonly?: boolean): ColorSchema<Src>;
+    hidden(isHidden?: boolean): ColorSchema<Src>;
     /**
      * How this field is laid out in the editor when it is the item of an array
      * or record: `{ as: "inline" }` renders the field itself inside each row,

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

@@ -50,8 +50,8 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     from(from: string): DateSchema<Src>;
     to(to: string): DateSchema<Src>;
     nullable(): DateSchema<Src | null>;
-    readonly(): DateSchema<Src>;
-    hidden(): DateSchema<Src>;
+    readonly(isReadonly?: boolean): DateSchema<Src>;
+    hidden(isHidden?: boolean): DateSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -54,8 +54,8 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     from(from: string): DateTimeSchema<Src>;
     to(to: string): DateTimeSchema<Src>;
     nullable(): DateTimeSchema<Src | null>;
-    readonly(): DateTimeSchema<Src>;
-    hidden(): DateTimeSchema<Src>;
+    readonly(isReadonly?: boolean): DateTimeSchema<Src>;
+    hidden(isHidden?: boolean): DateTimeSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -48,8 +48,8 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): FileSchema<Src | null>;
-    readonly(): FileSchema<Src>;
-    hidden(): FileSchema<Src>;
+    readonly(isReadonly?: boolean): FileSchema<Src>;
+    hidden(isHidden?: boolean): FileSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -21,11 +21,6 @@ export type FilesOptions = {
      * a directory with every other one.
      */
     directory: "/public" | `/public/${string}`;
-    /**
-     * Whether remote files are allowed
-     * @default false
-     */
-    remote?: boolean;
 };
 /**
  * Metadata for a file entry in the files record
@@ -43,6 +38,8 @@ type FilesItemSrc = {
 /**
  * Define a collection of files.
  *
+ * Remote is off by default: call `.remote()` on the result to allow remote files.
+ *
  * @example
  * ```typescript
  * const schema = s.files({

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

@@ -5,9 +5,10 @@ import type { SerializedSchema } from "./index.js";
  * The one answer to that question. There used to be two — `hasRemoteFileSchema`
  * in the server, gating whether `/save` demands remote credentials, and
  * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
- * and they disagreed about `s.images({ remote: true })`: the Studio's counted a
- * remote media record, the server's did not, because a media collection
- * serializes as a `record` of metadata rather than as an image schema.
+ * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * counted a remote media record, the server's did not, because a media
+ * collection serializes as a `record` of metadata rather than as an image
+ * schema.
  *
  * The server's answer was the wrong one, and silently so. With it false,
  * `/save` runs `saveOrUploadFiles` in `skip-remote` mode, and that mode does not
@@ -32,3 +33,20 @@ import type { SerializedSchema } from "./index.js";
  * instead would reintroduce exactly the silent skip described above.
  */
 export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;
+/**
+ * Does this schema hold any media at all — remote or not?
+ *
+ * The sibling of {@link hasRemoteFileSchema}, and the same walk minus the
+ * `remote` predicate. It answers the question an external record has to ask
+ * before it will accept a binding: an item schema containing media needs a
+ * `putFile`/`getFile` pair, and without one that is a schema error.
+ *
+ * It is a walk over the SERIALIZED schema for the reasons given above, and for
+ * one more that is specific to this question: the two cases most likely to be
+ * missed are invisible to a value type. A media collection (`s.images()` /
+ * `s.files()`) serializes as a record of metadata with no image schema inside
+ * it, and a richtext inline image lives in a constructor argument. A check
+ * written against the item TYPE would silently pass both — and the gallery case
+ * already has a data-loss incident attached to it (see above).
+ */
+export declare function hasMediaSchema(schema: SerializedSchema): boolean;

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

@@ -93,8 +93,8 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ImageSchema<Src | null>;
-    readonly(): ImageSchema<Src>;
-    hidden(): ImageSchema<Src>;
+    readonly(isReadonly?: boolean): ImageSchema<Src>;
+    hidden(isHidden?: boolean): ImageSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -35,11 +35,6 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * - s.record(s.string(), s.string()) for locale-based alt text
      */
     alt?: AltSchema;
-    /**
-     * Whether remote images are allowed
-     * @default false
-     */
-    remote?: boolean;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
@@ -79,7 +74,7 @@ type ImagesItemSrc = {
  *
  * `directory` is required — it decides where uploads land, so it is not something
  * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
- * text, remote disabled.
+ * text, remote disabled. Call `.remote()` on the result to allow remote images.
  *
  * @example
  * ```typescript

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

@@ -17,11 +17,12 @@ import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.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 | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedSettingsSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;
@@ -97,15 +98,23 @@ export declare abstract class Schema<Src extends SelectorSource> {
      *
      * This is a UI-only flag: the field is rendered disabled in the editor, but
      * the value is not otherwise validated or enforced differently.
+     *
+     * The flag defaults to `true`, so `.readonly()` and `.readonly(true)` are the
+     * same thing. `.readonly(false)` leaves the field editable, which is what a
+     * schema is anyway - pass it when the decision comes from a variable.
      */
-    abstract readonly(): Schema<Src>;
+    abstract readonly(isReadonly?: boolean): Schema<Src>;
     /**
      * Hide this field from the Val editor.
      *
      * This is a UI-only flag: the field is not rendered in the editor, but the
      * value is still stored, validated and serialized as normal.
+     *
+     * The flag defaults to `true`, so `.hidden()` and `.hidden(true)` are the
+     * same thing. `.hidden(false)` leaves the field visible, which is what a
+     * schema is anyway - pass it when the decision comes from a variable.
      */
-    abstract hidden(): Schema<Src>;
+    abstract hidden(isHidden?: boolean): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;
     /**
      * @param scope Which paths the caller needs a preview for. Absent means the

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

@@ -47,8 +47,8 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): KeyOfSchema<Sel, Src | null>;
-    readonly(): KeyOfSchema<Sel, Src>;
-    hidden(): KeyOfSchema<Sel, Src>;
+    readonly(isReadonly?: boolean): KeyOfSchema<Sel, Src>;
+    hidden(isHidden?: boolean): KeyOfSchema<Sel, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -31,8 +31,8 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): LiteralSchema<Src | null>;
-    readonly(): LiteralSchema<Src>;
-    hidden(): LiteralSchema<Src>;
+    readonly(isReadonly?: boolean): LiteralSchema<Src>;
+    hidden(isHidden?: boolean): LiteralSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -35,8 +35,8 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): NumberSchema<Src | null>;
-    readonly(): NumberSchema<Src>;
-    hidden(): NumberSchema<Src>;
+    readonly(isReadonly?: boolean): NumberSchema<Src>;
+    hidden(isHidden?: boolean): NumberSchema<Src>;
     max(max: number): NumberSchema<Src>;
     min(min: number): NumberSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];

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

@@ -55,8 +55,8 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ObjectSchema<Props, Src | null>;
-    readonly(): ObjectSchema<Props, Src>;
-    hidden(): ObjectSchema<Props, Src>;
+    readonly(isReadonly?: boolean): ObjectSchema<Props, Src>;
+    hidden(isHidden?: boolean): ObjectSchema<Props, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array