@valbuild/core 0.129.0 → 0.134.0

package/CHANGELOG.md

@@ -1,5 +1,193 @@
 # @valbuild/core
 
+## 0.134.0
+
+### Minor Changes
+
+- [#690](https://github.com/valbuild/val/pull/690) [`16c49ea`](https://github.com/valbuild/val/commit/16c49ea6dd97c7a96bbfdf211af9bab5884579e2) Thanks [@freekh](https://github.com/freekh)! - Read a view with `useVal` / `fetchVal`.
+
+  A `s.view()` field reads as a pointer with no properties on it. It can now be handed to a reader, which resolves it to the module it names:
+
+  ```tsx
+  const page = useVal(pageVal);
+  const header = useVal(page.header); // the header module's content, typed
+  ```
+
+  The point is single source of truth rather than a new capability: the page declares which module it shows, and a component follows that declaration instead of importing the target a second time. Change `s.view(headerVal)` to `s.view(navVal)` and the reader follows; an import would have kept reading the header.
+
+  The readers that take a MODULE rather than a value follow the same rule — `useValKey`, `useValRoute`, `useValRouteUrl` and the `fetchVal*` counterparts, in both the Next and TanStack packages:
+
+  ```tsx
+  const page = useVal(pageVal);
+  const note = useValRoute(page.notes, params); // the router module the view names
+  ```
+
+  Works in draft mode, including when the page itself has a pending edit. Two things to know:
+
+  - **Resolve a handle in the component that read the module containing it.** A handle carries the module it points at, and that cannot survive serialization — so one passed from a server component to a client component as a prop arrives empty. It throws with an explanation rather than handing back the pointer. This is why it throws rather than returning nothing: every one of the route and key readers already uses `null` / `undefined` to mean "no such entry", so a quiet answer would be indistinguishable from a 404.
+  - **`ValView<Source>` is now a member of `SelectorSource`**, since a reader accepts one.
+
+- [#680](https://github.com/valbuild/val/pull/680) [`eaa265e`](https://github.com/valbuild/val/commit/eaa265e78d9f6d2a1b685c38901612b8a3704eed) Thanks [@freekh](https://github.com/freekh)! - Add `s.view()`: point at another module, so editors can reach it from the page it belongs to.
+
+  Content that has to live in its own module — a `keyOf` target, shared settings, a route-keyed record — is invisible from the page an editor thinks of it as part of. A view field puts a row on that page's screen that leads to it:
+
+  ```ts
+  import employeesVal from "../data/employees.val";
+
+  const schema = s.object({
+    title: s.string(),
+    employees: s.view(employeesVal),
+  });
+
+  export default c.define("/app/menneskene/page.val.ts", schema, {
+    title: "Våre folk",
+    employees: { view: "/data/employees.val.ts" },
+  });
+  ```
+
+  The source is a pointer and nothing else. The module it names keeps its own source, patches, validation and address, and an editor who follows the row lands on that module's own screen — so it is clear they are changing something other pages use too.
+
+  A few things worth knowing:
+
+  - **The path autocompletes, and a wrong one does not compile.** A module now carries its own id in its type, so the source type of the field above is the literal `{ view: "/data/employees.val.ts" }`.
+  - **It is not readable in code.** `useVal(pageVal).employees` is a `ValView<…>` — an opaque pointer with no fields on it. Read the module it names directly, as before.
+  - **`view` is now a reserved object key**, like `_type` and `patch_id`: `s.object({ view: ... })` no longer compiles. A single `view: string` key is what a view pointer looks like, and an ordinary object with that shape would be indistinguishable from one.
+  - **Views may not form a cycle.** `A → B → A`, and a module viewing itself, are reported as module errors by `val validate` and in the Studio.
+  - **A pointer that disagrees with its schema is repaired automatically.** It can only happen in hand-written JSON, and the schema is the authority, so `val validate --fix` and saving in the Studio both write the module the schema names.
+  - **A view's `hidden` and `readonly` are its own, never the module's it points at.** A view whose target is hidden is still shown, and still leads there.
+
+  That last one comes with a change to what `hidden()` means on a **module's own schema**, which is the other half of making a shared module usable:
+
+  ```ts
+  // Not in the nav, and on exactly one page.
+  export default c.define("/data/employees.val.ts", s.record(...).hidden(), { ... });
+  ```
+
+  It now means the nav does not list the module — the Explorer for an ordinary module, Media for a gallery — and nothing more. Previously it also blanked the module's own page, so a module you had hidden was still in the nav and showed nothing when opened. A hidden module is now reached from an `s.view()` row, from search or from a validation error, and renders in full when you get there.
+
+  One gap worth naming rather than leaving to be discovered: a view pointing at a
+  module the project does not have is reported by the FIELD — the row says the
+  target is missing — but not by `val validate`. The schema check compares the
+  pointer against the schema, and the cycle check deliberately skips a target that
+  is not a module of the project, so neither catches it. A project-level check
+  belongs with them and is not here yet.
+
+## 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";
@@ -65,6 +65,11 @@ export { type SerializedCodeSchema, type CodeOptions, type CodeLanguage, CodeSch
 export { type ColorFormat, type ParsedColor, COLOR_FORMATS, DEFAULT_COLOR_FORMAT, } from "./schema/colorFormat.js";
 export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetime.js";
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
+export { type SerializedValViewSchema, ValViewSchema } from "./schema/view.js";
+export { type ValViewSource, isValViewSource } from "./source/view.js";
+export type { ValView } from "./selector/view.js";
+export type { ValViewHandle, ResolvableModule } from "./source/viewHandle.js";
+import { createViewHandle, isViewHandle, resolveViewedModule, viewHandleModule, viewModulesOf } from "./source/viewHandle.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
 export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtext.js";
 export { type SerializedDiscriminatedUnionSchema, type DiscriminatedUnionSourceOf, DiscriminatedUnionSchema, } from "./schema/discriminatedUnion.js";
@@ -85,6 +90,11 @@ declare const Internal: {
     VERSION: {
         core: string;
     };
+    createViewHandle: typeof createViewHandle;
+    isViewHandle: typeof isViewHandle;
+    resolveViewedModule: typeof resolveViewedModule;
+    viewHandleModule: typeof viewHandleModule;
+    viewModulesOf: typeof viewModulesOf;
     mediaUrl: typeof mediaUrl;
     resolveMedia: typeof resolveMedia;
     isRemoteMediaPath: typeof isRemoteMediaPath;

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

@@ -10,6 +10,7 @@ import { richtext } from "./schema/richtext.js";
 import { image } from "./schema/image.js";
 import { literal } from "./schema/literal.js";
 import { keyOf } from "./schema/keyOf.js";
+import { view } from "./schema/view.js";
 import { record } from "./schema/record.js";
 import { file } from "./schema/file.js";
 import { fileset } from "./schema/fileset.js";
@@ -175,6 +176,23 @@ export type InitSchema = {
      *
      */
     readonly keyOf: typeof keyOf;
+    /**
+     * Show another module as part of this one, in the Val editor only.
+     *
+     * The source is a pointer — `{ view: "/other.val.ts" }` — and nothing else.
+     * The module it names keeps its own source, patches, validation and address;
+     * the editor shows a row here that navigates to it.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({ shared: s.view(otherVal), title: s.string() });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     *
+     */
+    readonly view: typeof view;
     /**
      * Define a record.
      *
@@ -381,6 +399,7 @@ export declare function initSchema(): {
         val?: never;
         _type?: never;
         _ref?: never;
+        view?: never;
         andThen?: never;
         assert?: never;
         fold?: never;
@@ -397,6 +416,7 @@ export declare function initSchema(): {
     image: typeof image;
     literal: <T extends string>(value: T) => import("./index.js").LiteralSchema<T>;
     keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./index.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./index.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./index.js").RawString : never : never>;
+    view: <M extends import("./selector/index.js").GenericSelector<import("./source/index.js").Source> & import("./module.js").ValModuleBrand>(valModule: M) => import("./index.js").ValViewSchema<import("./module.js").ModuleIdOf<M>, M extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S : never>;
     record: typeof record;
     file: typeof file;
     fileset: (options: import("./schema/fileset.js").FilesetOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{

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

@@ -6,10 +6,27 @@ import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
 declare const brand: unique symbol;
-export type ValModule<T extends SelectorSource> = SelectorOf<T> & ValModuleBrand;
-export type ValModuleBrand = {
+declare const idBrand: unique symbol;
+export type ValModule<T extends SelectorSource, Id extends string = string> = SelectorOf<T> & ValModuleBrand<Id>;
+/**
+ * The brand that says "this is a module", carrying the module's own id.
+ *
+ * `Id` is inferred from {@link define}'s first argument, so a module's PATH is
+ * in its type. That is what lets `s.view(fooVal)` produce a schema whose source
+ * type is the literal `{ view: "/foo.val.ts" }` — the path autocompletes at the
+ * call site, and a source that names a different module than the schema does is
+ * a type error rather than something validation has to catch later.
+ *
+ * Defaulted to `string` so every `ValModule<T>` written without it keeps
+ * meaning what it did. The property is covariant, so a module with a known id
+ * is still assignable everywhere `ValModule<T>` is expected.
+ */
+export type ValModuleBrand<Id extends string = string> = {
     [brand]: "ValModule";
+    [idBrand]: Id;
 };
+/** A module's own path, read back off its type. */
+export type ModuleIdOf<M> = M extends ValModuleBrand<infer Id> ? Id : string;
 export type InferValModuleType<T extends ValModule<SelectorSource>> = T extends GenericSelector<infer S> ? S : never;
 export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSource extends T ? T : T extends RawString ? string : T extends {
     [key in string]: SelectorSource;
@@ -32,8 +49,8 @@ export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSourc
  * external at all.
  */
 type InlineEntriesFor<S> = S extends ExternalRecordSrc<infer Item, string, boolean> ? Record<string, Item> : never;
-export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
-schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>> | InlineEntriesFor<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
+export declare function define<T extends Schema<SelectorSource>, Id extends string>(id: Id, // TODO: `/${string}`
+schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>> | InlineEntriesFor<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>, Id>;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
 /**
  * Whether `value` is a Val module, i.e. something {@link define} produced.

package/dist/declarations/src/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 {};