@valbuild/core 0.129.0 → 0.130.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @valbuild/core
 
+## 0.130.0
+
+### Patch Changes
+
+- [#663](https://github.com/valbuild/val/pull/663) [`8425378`](https://github.com/valbuild/val/commit/8425378c315ea46b5d822f1130b633e0449ff1b0) Thanks [@freekh](https://github.com/freekh)! - A value that has not been written yet offers to create it, instead of looking broken
+
+  Opening an array item or a record entry whose value is `null` rendered the item
+  schema's fields over nothing, so every one of them reported **Not Found** — a
+  column of broken fields where the truth is one fact about the value: nobody has
+  written it. It now shows one **Create** button.
+
+  A field inside an object always had this — the checkbox beside its label — but
+  a value opened on its own has no such wrapper, and that is exactly what
+  navigating to an entry does. Both places now agree.
+
+  This is most visible with a record whose keys are declared by its schema
+  (`s.record(s.locale(), …)` or `s.record(s.enum("a", "b"), …)`), where an entry
+  nobody has written is `null` rather than absent. There the wording follows: an
+  unwritten entry reads as **Not translated** in the list, and the button says
+  **Write this translation** rather than Create.
+
+  Also fixed: `Internal.resolvePath` reported a record entry that exists with a
+  falsy value — `null`, but equally `""`, `0` and `false`, in any record — as a
+  key the record does not have, so nothing could resolve a path to one.
+
+- [#679](https://github.com/valbuild/val/pull/679) [`473a185`](https://github.com/valbuild/val/commit/473a185f70351b44388f3bc1852649e2c1dbe001) Thanks [@freekh](https://github.com/freekh)! - `.preview()` now names a value wherever the Studio shows it, including a module's own root
+
+  Wherever the Studio shows a piece of content to a human it has to answer three
+  questions: what is this called, what is it, what does it look like. Every
+  surface answered them itself, out of the path, and they disagreed — the same
+  record entry read `blog1` in the heading, "Blog 1" in the scope trail and
+  `/blogs/blog1` in the sitemap. They now give one answer, and it is the one you
+  wrote:
+
+  ```ts
+  s.record(
+    s.object({ title: s.string(), author: s.string(), cover: s.image() }),
+  ).preview((blog) => ({
+    title: blog.title,
+    subtitle: blog.author,
+    image: blog.cover,
+  }));
+  ```
+
+  That title, subtitle and image are what the heading, list rows, search hits,
+  cards and chosen references show. Nothing is required: a project with no
+  `.preview()` reads exactly as it did — the route, the key, `[#3](https://github.com/valbuild/val/issues/3)`, or the
+  prettified file name — so this is somewhere to improve from rather than
+  something to adopt.
+
+  **`.preview()` on a module's own schema now works.** It was accepted and never
+  run: a preview was only ever reified by a CONTAINER for its rows, and a module
+  root has no container. So `c.define("/content/authors.val.ts", s.record(…)
+.preview(…), …)` can name the module itself — "Forfattere" rather than
+  `authors.val.ts` — and the same is true of a field of an object.
+
+  **A page's URL is carried separately from its title.** A route is not a worse
+  name for a page, it is the page's identity: two drafts both titled "Launch" are
+  told apart by `/blog/launch-2026` and by nothing else. Title a page with
+  `.preview()` and its route moves to the line under the heading rather than
+  disappearing.
+
+  Two things a preview is deliberately NOT used for, because a preview is a
+  closure over source and so changes as an editor types:
+
+  - The breadcrumb, the Explorer and the Pages tree stay path segments. A trail
+    of titles names three things and locates none of them. The one exception is a
+    page, whose trail is its ROUTE instead of the file it is stored in — nobody
+    reaches a page through the file.
+  - Help text. `.describe()` is input help and is shown where a field or a key is
+    being ENTERED; a record key's description no longer appears in the heading,
+    where the key cannot be edited, and appears in every form that asks for one.
+
+  Also fixed: a just-uploaded image stayed blank until save in list rows, headings
+  and reference dropdowns, which built the URL of the published file rather than
+  the pending patch's.
+
+- [#677](https://github.com/valbuild/val/pull/677) [`64f0de3`](https://github.com/valbuild/val/commit/64f0de339b8621cb5a6c422dfe55cae5b2bbe2a0) Thanks [@freekh](https://github.com/freekh)! - A guided tour of the Studio, and a `studio.tour` setting to turn it off
+
+  Editors kept asking what Pages, Media and Data are for. The three words are
+  precise inside Val and vague everywhere else, and the Studio said each of them
+  in three places — the rail tooltip, the panel header, the empty state — without
+  ever defining any.
+
+  **A guided tour**, offered by a glowing "Take a tour" button on the empty editor
+  at `/val/~` and kept permanently in **Quick actions**: welcome, then Pages, Media
+  and Data where the project has them, then the assistant where there is one, then
+  Review, Preview and Publish. It never opens itself, and the glow stops for good
+  once somebody has been through it on that browser.
+
+  Turn it off for the whole project under **Settings → Studio** — a new
+  `studio.tour` field on `s.settings()`, unset meaning the tour is offered. A team
+  that finds it noisy switches it off once, for everyone, instead of each person
+  dismissing it on each machine; the tour stays in Quick actions for anyone who
+  wants it.
+
+  Also, for the same first-run problem:
+
+  - **Rail tooltips carry a definition** under the label: "The pages of your site,
+    by URL", "Shared images and files, uploaded once", "Content that is not tied
+    to one page".
+  - **The empty editor is a short glossary** of the destinations this project
+    actually has, rather than "No item selected".
+  - **Empty states explain instead of reporting.** "No pages yet" now says who
+    creates the routes pages go under; "No galleries yet" says what a gallery is
+    for.
+  - **A project with a single media gallery opens it**, so Media shows media
+    instead of one collapsed row named after a module file.
+  - **A site map of twenty pages or fewer arrives open.** With a home page at `/`
+    the whole site nests under one root row, so Pages used to show a single row
+    called Home. Larger sites keep the old behaviour.
+  - **Settings points at Account** for the per-person settings — the theme, and
+    how the Studio behaves on this machine.
+  - Page rows with children now carry `aria-expanded`, as the media panel's rows
+    always did.
+
 ## 0.129.0
 
 ### Minor Changes

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

@@ -54,7 +54,7 @@ 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 LocalesSettingsSource, type AssistantAvailability, type ThemeSettingsSource, type ThemeRadius, ASSISTANT_SETTINGS_MAX_LENGTH, THEME_LOGO_DIRECTORY, THEME_RADIUS_STEPS, THEME_RADIUS_LENGTHS, assistantAvailability, } from "./source/settings.js";
+export { type SettingsSource, type AssistantSettingsSource, type LocalesSettingsSource, type AssistantAvailability, type ThemeSettingsSource, type StudioSettingsSource, type ThemeRadius, ASSISTANT_SETTINGS_MAX_LENGTH, THEME_LOGO_DIRECTORY, THEME_RADIUS_STEPS, THEME_RADIUS_LENGTHS, assistantAvailability, } from "./source/settings.js";
 export { type ResolvedSettingsModule, SETTINGS_MODULE_CONVENTION, isRootModuleFilePath, resolveSettingsModule, } from "./settingsModule.js";
 export { type Locale, localeTagError, localeOfValue } from "./locale.js";
 export { type SerializedLocaleSchema, LocaleSchema } from "./schema/locale.js";

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

@@ -2,6 +2,32 @@ import { Schema } from "./schema/index.js";
 import { SelectorSource } from "./selector/index.js";
 import { ImageSource } from "./source/media.js";
 import { ModuleFilePath, SourcePath } from "./val/index.js";
+/**
+ * THE RULE, and the only sentence that needs to be remembered:
+ *
+ *   **`.describe()` is INPUT HELP and is shown wherever that field — or a
+ *   record's key — is being ENTERED; `.preview()` is a NAME and is shown
+ *   wherever the value is REFERRED TO rather than edited; `.render()` is
+ *   LAYOUT and applies only while the field is open in front of you.**
+ *
+ * The test that settles every case: **can the reader change something here?**
+ * If yes it is a place for a description — the input beside a label, the key
+ * box in "New entry", "Rename key", "Duplicate", "New page", the key half of a
+ * reference dropdown. If no, it is a place for a preview — a list row, a
+ * reference once chosen, a search hit, a sitemap row, the heading of what you
+ * navigated to.
+ *
+ * That is why a description is plain data on the serialized schema and a
+ * preview is a closure: a description is true before any value exists and says
+ * the same thing to everyone filling the field in, and a preview cannot exist
+ * without the one value it names. So a description must never be used as a
+ * subtitle — it would repeat one sentence under every row of a list — and a
+ * preview must never be used as help text, because there is nothing to preview
+ * until after the value has been entered.
+ *
+ * None of the three substitutes for another: a field with a perfect
+ * description still previews as `#3` until someone writes the preview.
+ */
 /**
  * A PREVIEW is how a VALUE is shown wherever a preview of it is needed — a row
  * in a sortable list, a key in a reference dropdown, a search hit, a
@@ -76,14 +102,12 @@ export type ArrayPreview = {
     items: [index: number, value: PreviewItem][];
 };
 /**
- * Main preview type.
- *
- * Deliberately not exported: `parent` is the discriminant, and every consumer
- * narrows on it rather than on the union as a whole. There is no `layout` here
- * on purpose - how a preview is laid out is the editor's business, not the
- * schema's.
+ * How a CONTAINER's children preview. `parent` is the discriminant, and every
+ * consumer narrows on it rather than on the union as a whole. There is no
+ * `layout` here on purpose - how a preview is laid out is the editor's
+ * business, not the schema's.
  */
-type PreviewTypes = RecordPreview | ArrayPreview;
+export type PreviewRows = RecordPreview | ArrayPreview;
 type WithStatus<T> = {
     status: "error";
     message: string;
@@ -94,7 +118,40 @@ type WithStatus<T> = {
     status: "success";
     data: T;
 };
-export type ReifiedPreview = Record<SourcePath | ModuleFilePath, WithStatus<PreviewTypes>>;
+/**
+ * Everything known about ONE path, which is two independent things.
+ *
+ * They are separate fields rather than a union because a path can have both,
+ * and that is not a corner case: `s.array(section).preview(...)` where
+ * `section` also previews is a section list that shows its rows AND names
+ * itself when it is nested in something. One of them would have had to win.
+ *
+ * - {@link self} - what THIS value is called, from its own schema's
+ *   `.preview(...)`. This is the only answer for a value with no container to
+ *   ask: a module root (whose `.preview` was never run before this existed) and
+ *   any field of an object.
+ * - {@link rows} - what its CHILDREN are called, from the ITEM schema's
+ *   `.preview(...)`, reified by the container. Kept alongside `self` rather
+ *   than derived from the children's `self` entries because a list needs every
+ *   row in one answer, and because an EMPTY list still has to preview as an
+ *   empty list - which is a fact about the schema, not about any value.
+ */
+export type PreviewNode = {
+    self?: PreviewItem;
+    rows?: PreviewRows;
+};
+export type ReifiedPreview = Record<SourcePath | ModuleFilePath, WithStatus<PreviewNode>>;
+/**
+ * Fold `incoming` into `target`, path by path. MUTATES `target`.
+ *
+ * Every `executePreview` used to copy child results across with a plain
+ * assignment, which was fine while one path held one thing. It no longer does:
+ * a container writes `rows` at its own path and its `self` arrives from the
+ * same walk, so an overwrite silently drops whichever landed first. Merging is
+ * per FIELD, and an error at a path beats any data there - a preview that threw
+ * must not be reported as a preview that is merely absent.
+ */
+export declare function mergePreviewInto(target: ReifiedPreview, incoming: ReifiedPreview): void;
 /**
  * Which paths a preview is being computed FOR.
  *

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

@@ -1,4 +1,30 @@
 import type { SerializedSchema } from "./schema/index.js";
+/**
+ * THE RULE, and the only sentence that needs to be remembered:
+ *
+ *   **`.describe()` is INPUT HELP and is shown wherever that field — or a
+ *   record's key — is being ENTERED; `.preview()` is a NAME and is shown
+ *   wherever the value is REFERRED TO rather than edited; `.render()` is
+ *   LAYOUT and applies only while the field is open in front of you.**
+ *
+ * The test that settles every case: **can the reader change something here?**
+ * If yes it is a place for a description — the input beside a label, the key
+ * box in "New entry", "Rename key", "Duplicate", "New page", the key half of a
+ * reference dropdown. If no, it is a place for a preview — a list row, a
+ * reference once chosen, a search hit, a sitemap row, the heading of what you
+ * navigated to.
+ *
+ * That is why a description is plain data on the serialized schema and a
+ * preview is a closure: a description is true before any value exists and says
+ * the same thing to everyone filling the field in, and a preview cannot exist
+ * without the one value it names. So a description must never be used as a
+ * subtitle — it would repeat one sentence under every row of a list — and a
+ * preview must never be used as help text, because there is nothing to preview
+ * until after the value has been entered.
+ *
+ * None of the three substitutes for another: a field with a perfect
+ * description still previews as `#3` until someone writes the preview.
+ */
 /**
  * A RENDER is how the FIELD ITSELF is laid out in the editor, and it applies
  * only when you are looking at the field: `.render({ as: "inline" })` on an

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

@@ -41,10 +41,13 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     /**
      * 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.
      *
@@ -91,7 +94,7 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     }[];
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
-    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/boolean.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";
@@ -27,10 +27,13 @@ export declare class BooleanSchema<Src extends boolean | 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.
      *
@@ -93,6 +96,5 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const boolean: () => BooleanSchema<boolean>;

package/dist/declarations/src/schema/code.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 { RawString } from "./string.js";
@@ -58,10 +58,13 @@ export declare class CodeSchema<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.
      *
@@ -143,6 +146,5 @@ export declare class CodeSchema<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 code: (options?: CodeOptions) => CodeSchema<RawString>;

package/dist/declarations/src/schema/color.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 { ColorFormat } from "./colorFormat.js";
@@ -53,10 +53,13 @@ export declare class ColorSchema<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.
      *
@@ -129,6 +132,5 @@ export declare class ColorSchema<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 color: (options?: ColorOptions) => ColorSchema<RawString>;

package/dist/declarations/src/schema/date.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 { RawString } from "./string.js";
@@ -46,10 +46,13 @@ export declare class DateSchema<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.
      *
@@ -132,7 +135,6 @@ export declare class DateSchema<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 date: (options?: Record<string, never>) => DateSchema<RawString>;
 export {};

package/dist/declarations/src/schema/datetime.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 { RawString } from "./string.js";
@@ -50,10 +50,13 @@ export declare class DateTimeSchema<Src extends string | 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.
      *
@@ -159,7 +162,6 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const datetime: (options?: Record<string, never>) => DateTimeSchema<RawString>;
 export {};

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

@@ -62,10 +62,13 @@ export declare class DiscriminatedUnionSchema<Key extends string, T extends Disc
     /**
      * 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.
      *
@@ -165,6 +168,6 @@ export declare class DiscriminatedUnionSchema<Key extends string, T extends Disc
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedDiscriminatedUnionSchema;
-    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 discriminatedUnion: <Key extends string, T extends DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => DiscriminatedUnionSchema<Key, T, DiscriminatedUnionSourceOf<Key, T>>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult } 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";
@@ -51,10 +51,13 @@ export declare class EnumSchema<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.
      *
@@ -120,7 +123,6 @@ export declare class EnumSchema<Src extends string | null> extends Schema<Src> {
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedEnumSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * Define a string that must be one of a fixed set of values.

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;