@valbuild/core 0.128.0 → 0.130.0

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

@@ -4,7 +4,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { FilesetEntryMetadata } from "./fileset.js";
 export type FileOptions = {
@@ -40,10 +40,13 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -145,7 +148,6 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * A file picked from a gallery. Its mime type lives in the gallery, so the

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

@@ -3,7 +3,7 @@ import { GalleryImageSource, ImageSource } from "../source/media.js";
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { AltSource, ImagesetEntryMetadata } from "./imageset.js";
 /**
@@ -85,10 +85,13 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -219,7 +222,6 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * An image picked from a gallery. Its dimensions and mime type live in the

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

@@ -270,13 +270,41 @@ export declare abstract class Schema<Src extends SelectorSource> {
     abstract hidden(isHidden?: boolean): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;
     /**
+     * This value's preview, and every preview below it.
+     *
+     * The default is the whole of it for a LEAF: a leaf has nothing below it, so
+     * all it can contribute is {@link PreviewNode.self}. Containers override this
+     * and recurse; object and discriminated union add nothing of their own beyond
+     * the self they inherit here, and array and record add `rows`.
+     *
      * @param scope Which paths the caller needs a preview for. Absent means the
      * whole module, which is what every caller passed before scoping existed.
      * See {@link PreviewScope}: a container prunes recursion where nothing is
      * wanted, and previews a WINDOW when its own path is not wanted but some of
      * its items are — which is the single-visible-row case.
+     * @param selfIsReifiedByParent Set by an array or record on its DIRECT items,
+     * and by nothing else. Such an item's preview is the same closure the
+     * container is already running into {@link PreviewNode.rows}, so emitting a
+     * `self` for it as well would call the user's closure twice per row — which
+     * it did, and which the scoped-preview tests caught by counting. The flag
+     * does not travel further down: a grandchild is nobody's row.
+     */
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
+    /**
+     * THIS value as a preview, at its own path — `{ self }` and nothing else.
+     *
+     * Every schema can produce one, which is the point: before this existed a
+     * value's preview was reified only by its CONTAINER, so a value with no
+     * container had none. A module root is exactly that, and `.preview(...)` on
+     * a module's own schema was therefore dead code — the studio showed the file
+     * name and nothing a developer wrote could change it. So is any field of an
+     * object, which reifies no rows.
+     *
+     * Gated on {@link PreviewScope.wants} rather than `wantsUnder`: a caller
+     * asking about a CONTAINER wants its rows, and computing a self for every
+     * descendant on the way past would run each item's closure twice.
      */
-    protected abstract executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executeSelfPreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
     /**
      * This value AS A PREVIEW — what a container's row, a reference dropdown or
      * a search hit shows for it. Runs the schema's own `preview` closure;

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

@@ -5,7 +5,7 @@ import { Source, SourceObject } from "../source/index.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { RawString } from "./string.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 export type SerializedKeyOfSchema = {
     type: "keyOf";
@@ -45,10 +45,13 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -117,7 +120,6 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const keyOf: <Src extends GenericSelector<SourceObject> & ValModuleBrand>(valModule: Src) => KeyOfSchema<Src, KeyOfSelector<Src>>;
 export {};

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -31,10 +31,13 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -99,6 +102,5 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const literal: <T extends string>(value: T) => LiteralSchema<T>;

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

@@ -1,5 +1,5 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -115,7 +115,6 @@ export declare class LocaleSchema<Src extends string | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * Define one of the project's languages.

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -33,10 +33,13 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -115,7 +118,6 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const number: (options?: NumberOptions) => NumberSchema<number>;
 export {};

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

@@ -53,10 +53,13 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -145,7 +148,7 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
 }
 export declare const object: <Props extends ObjectSchemaProps>(schema: Props) => ObjectSchema<Props, ObjectSchemaSrcOf<Props>>;
 export {};

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

@@ -111,10 +111,13 @@ RO extends boolean = false> extends Schema<Src> {
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -333,7 +336,7 @@ RO extends boolean = false> extends Schema<Src> {
      * defers).
      */
     validateJsonEntryContent(path: SourcePath, content: SelectorSource): ValidationErrors;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     /**

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { RichTextSource, RichTextOptions, SerializedRichTextOptions } from "../source/richtext.js";
 import { SourcePath } from "../val/index.js";
@@ -34,10 +34,13 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -138,7 +141,6 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const richtext: <O extends RichTextOptions>(options?: O) => RichTextSchema<O, RichTextSource<O>>;
 export {};

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

@@ -1,6 +1,6 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { SourcePath } from "../val/index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type RouteOptions = {
@@ -43,10 +43,13 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -135,7 +138,6 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const route: <T extends string>(options?: Record<string, never>) => RouteSchema<T>;
 export {};

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

@@ -119,7 +119,7 @@ export declare class SettingsSchema<Src extends {
     hidden(): SettingsSchema<Src>;
     protected executeCustomValidateAt(): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
 }
 /**
  * Define the project's settings.
@@ -141,11 +141,18 @@ export declare class SettingsSchema<Src extends {
  *     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.",
  *   },
+ *   theme: {
+ *     accent: "#2563eb",
+ *     radius: "tight",
+ *     logo: { path: "/public/val/brand/mark_a1b2c.png", width: 512, height: 512, mimeType: "image/png" },
+ *   },
  * });
  * ```
  *
- * 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.
+ * The Studio edits it under the cog at the foot of the left rail. The assistant
+ * is told `assistant.context` and `assistant.tone` on every message, and
+ * `theme` restyles the Studio's own chrome — see {@link ThemeSettingsSource},
+ * and note that it is the CMS being restyled, not the site.
  *
  * `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

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

@@ -1,5 +1,5 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -69,10 +69,13 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     /**
      * Describe this field.
      *
-     * The description is shown next to the field's label in the Val editor, so
-     * it is where you say what an editor needs to know but the field name cannot
-     * carry. It also travels in the serialized schema, which is what the AI
-     * assistant and the MCP tools read.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description also travels in the serialized
+     * schema, which is what the AI assistant and the MCP tools read.
      *
      * Pass `null` to clear a description set earlier.
      *
@@ -216,12 +219,6 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     preview(select: ItemPreviewInput<Src>): StringSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
-    /**
-     * Nothing: a string has no items, so there is nothing to preview. Its layout
-     * is a `render`, which travels in the serialized schema instead of through
-     * this pipeline.
-     */
-    protected executePreview(): ReifiedPreview;
 }
 export declare const string: <T extends string>(options?: Record<string, never>) => StringSchema<T>;
 export {};

package/dist/declarations/src/source/settings.d.ts

@@ -1,3 +1,4 @@
+import { ImageSource } from "./media.js";
 /**
  * The source of the project's settings module — `s.settings()`.
  *
@@ -22,8 +23,124 @@
  */
 export type SettingsSource = {
     assistant?: AssistantSettingsSource;
+    theme?: ThemeSettingsSource;
     locales?: LocalesSettingsSource;
+    studio?: StudioSettingsSource;
 };
+/**
+ * How the Studio behaves for the people editing this project.
+ *
+ * Not how it looks — that is {@link ThemeSettingsSource} — and not one person's
+ * own preferences, which stay in their browser. This is the project's word on
+ * what its editors are offered, which is why it is content: a team that has
+ * decided something about the way they work should not need a developer and a
+ * deploy to say so.
+ */
+export type StudioSettingsSource = {
+    /**
+     * Whether editors are offered the guided tour of the Studio.
+     *
+     * Unset means yes, because the person this exists for is the one who has not
+     * answered any question yet. Setting it to `false` turns the offer off for
+     * everyone on the project, permanently and for good — which is the point:
+     * a team that finds it noisy can be rid of it once rather than each person
+     * dismissing it on each machine they use.
+     *
+     * It governs the OFFER, not the tour. Whoever wants it can still run it from
+     * Quick actions; what goes is the glowing button and the prompt on the empty
+     * editor. Whether a given person has already been through it is a fact about
+     * that browser and is not here.
+     */
+    tour?: boolean | null;
+};
+/**
+ * How the Studio looks in this project.
+ *
+ * Chrome, and only chrome: nothing here reaches a visitor to the site. It is
+ * the CMS that is being restyled, so that a project can make the tool it edits
+ * in feel like its own.
+ *
+ * This is deliberately NOT the light/dark switch. That one is per-person and
+ * per-machine (see `ValThemeProvider`, which keeps it in `localStorage`), and it
+ * has to stay that way — one editor working in a dark room is not a fact about
+ * the project. {@link ThemeSettingsSource.mode} is the project's DEFAULT for
+ * someone who has not chosen, which is a different statement.
+ */
+export type ThemeSettingsSource = {
+    /**
+     * The one colour the Studio's chrome is built from, as a hex string.
+     *
+     * Unset means Val's own green. What it replaces is not a single value but the
+     * whole ten-step brand ramp — `--colors-brand-green-100` through `-1000` —
+     * because every brand token in `index.css` points into that ramp, and light
+     * and dark pick different steps out of it. One accent therefore drives both
+     * modes, with nothing to keep in sync.
+     *
+     * Any hex is allowed rather than a list of approved ones, and that is safe
+     * for a measured reason rather than an optimistic one: the ramp is generated
+     * by reusing green's LIGHTNESS at each step and changing only the hue, and
+     * WCAG contrast is almost entirely a function of lightness. See
+     * `accentRamp` in `@valbuild/shared`, whose tests hold every
+     * foreground/background pair the chrome renders to AA across the hue circle.
+     */
+    accent?: string | null;
+    /**
+     * How round the Studio's corners are.
+     *
+     * Named steps rather than a length, for two reasons: a number input invites
+     * `7px`, which nothing in the chrome is drawn around, and the scale is Val's
+     * decision rather than the project's. See {@link THEME_RADIUS_LENGTHS} for
+     * what each one is worth.
+     */
+    radius?: ThemeRadius | null;
+    /**
+     * The mode the Studio opens in for someone who has not picked one.
+     *
+     * A default, not a setting: an editor who has flicked the switch behind the
+     * account button keeps their choice, and this never overrides it.
+     */
+    mode?: "dark" | "light" | null;
+    /**
+     * The project's own mark, shown where Val's is in the Studio.
+     *
+     * The top of the left rail on desktop, and beside the menu button on mobile.
+     * NOT the launcher that floats on the project's own site: there the mark says
+     * "this is Val", and a project's logo on its own page says nothing at all —
+     * see {@link THEME_LOGO_DIRECTORY} and `architecture/logo.md`.
+     *
+     * A square-ish mark rather than a wordmark, because the slot it goes in is
+     * 32px wide. A wide image is contained rather than cropped, so nothing is
+     * cut off — it is simply small.
+     */
+    logo?: ImageSource | null;
+};
+/**
+ * Where an uploaded logo goes.
+ *
+ * Its own directory rather than the `/public/val` default, so that the one
+ * image a project uploads through the settings panel does not land in the
+ * middle of its content's media. `val list-unused-files` reads what is
+ * referenced rather than where it sits, so nothing depends on this beyond
+ * tidiness.
+ */
+export declare const THEME_LOGO_DIRECTORY = "/public/val/brand";
+/** @see {@link ThemeSettingsSource.radius} */
+export type ThemeRadius = "square" | "tight" | "default" | "soft";
+export declare const THEME_RADIUS_STEPS: readonly ThemeRadius[];
+/**
+ * What each radius step is worth, as a `--radius` value.
+ *
+ * `--radius` is the only length in the Studio's chrome that is a token:
+ * `rounded-sm`, `rounded-md` and `rounded-lg` are all `calc(var(--radius) …)`
+ * in `tailwind.config.js`, which is around three hundred call sites moving on
+ * one value. `default` is what `index.css` declares, so selecting it and
+ * clearing the setting look the same — which is what makes this list the whole
+ * of the feature.
+ *
+ * `rounded-full` and the hand-written `rounded-t` / `-r` / `-b` cases do not
+ * follow, and that is visible at `soft`: a pill stays a pill.
+ */
+export declare const THEME_RADIUS_LENGTHS: Record<ThemeRadius, string>;
 /**
  * The languages this project publishes.
  *