@valbuild/core 0.128.0 → 0.130.0

package/CHANGELOG.md

@@ -1,5 +1,215 @@
 # @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
+
+- [#655](https://github.com/valbuild/val/pull/655) [`7d34ecc`](https://github.com/valbuild/val/commit/7d34ecce787a0709025ae7b4764cb6c3ad1f766b) Thanks [@freekh](https://github.com/freekh)! - A project can now make Val Studio look like its own.
+
+  `s.settings()` has a new `theme` section, edited under **Settings → Appearance**
+  in the Studio. It is content like everything else: edited as a draft, shown in
+  the publish diff, and the same for everyone working on the project.
+
+  ```ts
+  export default c.define("/settings.val.ts", s.settings(), {
+    theme: {
+      accent: "#2563eb",
+      radius: "tight",
+      mode: "light",
+    },
+  });
+  ```
+
+  **`accent` is one hex, and it restyles the whole chrome** — Publish, the active
+  rail item, focus rings, switches, the caret in a rich text field, and the
+  outlines the canvas draws around editable elements on your own page. Any colour
+  is allowed, not a list of approved ones, because what the accent replaces is a
+  ten-step ramp that is _generated_ from it: each step keeps the lightness of the
+  step it replaces and changes only the hue. WCAG contrast is almost entirely a
+  function of lightness, so every foreground/background pair the chrome renders
+  stays at AA — which is asserted across the hue circle, pure black and a
+  saturated yellow included, rather than argued for. One value drives both light
+  and dark mode, since the semantic tokens pick different steps of the ramp in
+  each.
+
+  **`radius`** is `square`, `tight`, `default` or `soft`, and moves every corner
+  in the Studio.
+
+  The accent also moves the outlines the canvas draws around editable elements on
+  your own page. Those are drawn inside your document, which has none of Val's
+  stylesheet, so the colour is sent to the page over the canvas protocol — which
+  means a project on an older `@valbuild/next` or `@valbuild/tanstack` than its
+  Studio keeps Val's green there until it upgrades, rather than breaking.
+
+  **`mode`** is the mode the Studio opens in for an editor who has never picked
+  one. It never overrides an editor who has — that choice stays theirs, per
+  person and per browser, behind the account button.
+
+  Every field is optional, and unset means Val's own look, so an existing
+  settings module needs no change.
+
+  Two smaller fixes that came with it:
+
+  - **A settings change is its own entry in the publish diff.** Editing the
+    assistant's tone used to collapse the entire settings module into one change
+    card labelled "Settings", because the patch that writes a settings field is
+    an `add`, and `PatchSets` had no case for a settings section — so it gave up
+    and grouped the whole module. Two unrelated settings edits now show as two
+    changes, each under the name the panel gives it.
+  - **The Val mark keeps its green.** It named a step of the brand ramp, so it
+    would have recoloured along with a project's accent. It has its own token now.
+
+- [#657](https://github.com/valbuild/val/pull/657) [`0c351c4`](https://github.com/valbuild/val/commit/0c351c4f97ae7f09772eab0e856ae69821b803b7) Thanks [@freekh](https://github.com/freekh)! - A project can put its own logo in Val Studio.
+
+  `s.settings()`'s `theme` section takes a `logo`, uploaded from **Settings →
+  Appearance**. It replaces Val's mark at the top of the left rail, and beside the
+  menu button below the desktop breakpoint — the two slots that say which
+  workspace you are in.
+
+  ```ts
+  export default c.define("/settings.val.ts", s.settings(), {
+    theme: {
+      logo: {
+        path: "/public/val/brand/mark_a1b2c.png",
+        width: 512,
+        height: 512,
+        mimeType: "image/png",
+      },
+    },
+  });
+  ```
+
+  It is an ordinary image field, so it comes with the upload, the alt text and
+  everything else `s.image()` has, and the file lands in `/public/val/brand` so it
+  does not sit in the middle of your content's media. A draft logo shows
+  immediately and publishes with the rest of your changes.
+
+  Two things are deliberate:
+
+  - **A square-ish mark, not a wordmark.** The slot is 32px wide. A wide image is
+    fitted into it rather than cropped, so all of it is there and none of it is
+    large.
+  - **Val's mark stays on the launcher that floats on your own site.** In the
+    Studio the mark labels the workspace, so your logo belongs there. On your own
+    page it labels the tool — it is the button that opens Val — and your logo
+    floating over your own website says nothing.
+
 ## 0.128.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, ASSISTANT_SETTINGS_MAX_LENGTH, 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.