@valbuild/core 0.117.0 → 0.121.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @valbuild/core
 
+## 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
+
+- [#589](https://github.com/valbuild/val/pull/589) [`c2d3c0e`](https://github.com/valbuild/val/commit/c2d3c0e6c2010c0a94c725d9dbaa618998773e8a) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.richtext()` options are flat.
+
+  The `style`, `block` and `inline` groups are gone — every option is a key of its
+  own. The names are unchanged, so updating a schema is only a matter of removing
+  the wrappers:
+
+  ```ts
+  // before
+  s.richtext({
+    style: { bold: true, italic: true },
+    block: { h1: true, ul: true },
+    inline: { a: true, img: s.image() },
+  });
+
+  // after
+  s.richtext({
+    bold: true,
+    italic: true,
+    h1: true,
+    ul: true,
+    a: true,
+    img: s.image(),
+  });
+  ```
+
+  The groups never carried any meaning the option names did not already have, and
+  they cost something real: an option name and its `ValRichText` theme key were
+  spelled differently (`block.h1` vs `theme.h1`), so the type that keeps a theme
+  exhaustive had to restate all thirteen options by hand. It is now a mapped type
+  over the options themselves — which also fixes an inconsistency in it: enabling
+  links with a schema (`a: s.route()`) rather than `a: true` now requires an `a`
+  key in the theme, the way `img` always has.
+
+  `ValRichText` themes were already flat and are unchanged. The serialized schema
+  that the server sends the Studio is flat too, so a project must not mix
+  `@valbuild/*` versions across this release.
+
 ## 0.117.0
 
 ### Patch Changes

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

@@ -50,6 +50,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";

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

@@ -20,17 +20,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/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/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/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

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

@@ -84,8 +84,8 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private validateMediaMimeType;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): RecordSchema<T, K, Src | null>;
-    readonly(): RecordSchema<T, K, Src>;
-    hidden(): RecordSchema<T, K, Src>;
+    readonly(isReadonly?: boolean): RecordSchema<T, K, Src>;
+    hidden(isHidden?: boolean): RecordSchema<T, K, Src>;
     router(router: ValRouter): RecordSchema<T, K, Src>;
     remote(): RecordSchema<T, K, Src>;
     /**

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

@@ -15,7 +15,7 @@ export type SerializedRichTextSchema = {
     /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
     preview?: true;
     opt: boolean;
-    options?: SerializedRichTextOptions & ValidationOptions;
+    options?: SerializedRichTextOptions;
     customValidate?: boolean;
     readonly?: boolean;
     hidden?: boolean;
@@ -40,8 +40,8 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     private recursiveAssert;
     nullable(): RichTextSchema<O, Src | null>;
-    readonly(): RichTextSchema<O, Src>;
-    hidden(): RichTextSchema<O, Src>;
+    readonly(isReadonly?: boolean): RichTextSchema<O, Src>;
+    hidden(isHidden?: boolean): RichTextSchema<O, 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/route.d.ts

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

@@ -0,0 +1,102 @@
+import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
+import { PreviewScope, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
+import { SelectorSource } from "../selector/index.js";
+import { SettingsSource } from "../source/settings.js";
+import { ModuleFilePath, SourcePath } from "../val/index.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type SerializedSettingsSchema = {
+    type: "settings";
+    /**
+     * The sections this settings schema knows about, keyed by name.
+     *
+     * Carried in full rather than reconstructed from the Val version, so a Studio
+     * that predates a section still deserializes the schema (it renders what it
+     * recognises and leaves the rest alone) instead of failing on an unknown
+     * shape.
+     */
+    items: Record<string, SerializedSchema>;
+    opt: boolean;
+    /**
+     * Present in the shape, never set by `s.settings()`.
+     *
+     * `render` and `preview` say how a value is drawn where it is an ITEM of an
+     * array or a record, and `customValidate` marks a user's `validate` closure. A
+     * settings module is not an item, and `s.settings()` takes no arguments to
+     * declare any of the three with — so nothing writes them.
+     *
+     * They are declared anyway, and with their real types rather than `never`, for
+     * two reasons: reading `schema.render` off a `SerializedSchema` has to stay
+     * legal (`isInlineRender` does exactly that), and a `?: never` member is typed
+     * `undefined`, which makes the whole `SerializedSchema` union stop being
+     * assignable to `Json` — and serialized schemas travel to the Studio and to
+     * the MCP tools as JSON.
+     */
+    render?: FieldRender;
+    preview?: true;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/**
+ * An object whose keys are all optional: absent means unset.
+ *
+ * Both the settings module itself and each of its sections are this. See
+ * {@link SettingsSource} for why settings cannot be an object schema, and
+ * {@link settings} for what a settings module holds.
+ *
+ * There is no `describe`, `validate`, `render` or `preview` on purpose: the
+ * shape is Val's, not the schema author's — `s.settings()` takes no arguments —
+ * and the Studio renders each section with a UI built for it.
+ */
+export declare class SettingsSchema<Src extends {
+    [key: string]: SelectorSource;
+} | null> extends Schema<Src> {
+    private readonly items;
+    private readonly opt;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): SettingsSchema<Src | null>;
+    readonly(): SettingsSchema<Src>;
+    hidden(): SettingsSchema<Src>;
+    protected executeCustomValidateAt(): ValidationError[];
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+}
+/**
+ * Define the project's settings.
+ *
+ * One settings module per project, at the root of the content tree — a module
+ * file path with no directory segment, `/settings.val.ts` by convention:
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {});
+ * ```
+ *
+ * Every section is optional, so `{}` is a complete settings module and stays
+ * one as sections are added. Fill in what the project needs:
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {
+ *   assistant: {
+ *     enabled: true,
+ *     context: "Val is a CMS for developers. British English, and 'Val' is never 'VAL'.",
+ *     tone: "Plain and direct. No exclamation marks, sentence case in headings.",
+ *   },
+ * });
+ * ```
+ *
+ * The Studio edits it under the cog at the foot of the left rail, and the
+ * assistant is told `assistant.context` and `assistant.tone` on every message.
+ *
+ * `s.settings()` takes no arguments: the shape is Val's, which is what lets the
+ * Studio render a UI built for each field rather than a generic form. A
+ * project's own global content — a site name, social links — belongs in a
+ * module of its own.
+ */
+export declare function settings(): SettingsSchema<SettingsSource>;

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

@@ -82,8 +82,8 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): StringSchema<Src | null>;
-    readonly(): StringSchema<Src>;
-    hidden(): StringSchema<Src>;
+    readonly(isReadonly?: boolean): StringSchema<Src>;
+    hidden(isHidden?: boolean): StringSchema<Src>;
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;

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

@@ -56,8 +56,8 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): UnionSchema<Key, T, Src | null>;
-    readonly(): UnionSchema<Key, T, Src>;
-    hidden(): UnionSchema<Key, T, Src>;
+    readonly(isReadonly?: boolean): UnionSchema<Key, T, Src>;
+    hidden(isHidden?: boolean): UnionSchema<Key, T, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * The variant schema a value takes, for a TAGGED union (string `key`). `null`

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

@@ -12,10 +12,11 @@ import { MediaSource } from "../source/media.js";
 import { AllRichTextOptions, RichTextSource } from "../source/richtext.js";
 import { RichTextSelector } from "./richtext.js";
 import { JsonSource } from "../source/json.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+import { SettingsSource } from "../source/settings.js";
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | MediaSource | JsonSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */