@valbuild/core 0.129.0 → 0.130.0

package/dist/{index-06bb2832.esm.js → index-71a59a88.esm.js}

@@ -411,8 +411,93 @@ var Schema = /*#__PURE__*/function () {
      * For example, if you have an object schema, you must assert each key / value pair manually.
      */
   }, {
-    key: "executePreviewItem",
+    key: "executePreview",
     value:
+    /**
+     * 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.
+     */
+    function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
+      if (selfIsReifiedByParent) {
+        return {};
+      }
+      return this.executeSelfPreview(sourcePath, src, scope);
+    }
+
+    /**
+     * 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.
+     */
+  }, {
+    key: "executeSelfPreview",
+    value: function executeSelfPreview(sourcePath, src, scope) {
+      if (src === null || src === undefined) {
+        return {};
+      }
+      if (!this.declaresItemPreview()) {
+        return {};
+      }
+      if (scope !== undefined && !scope.wants(sourcePath)) {
+        return {};
+      }
+      try {
+        // NB NB: the closure is user code.
+        var item = this.executePreviewItem(src);
+        if (item === null) {
+          return {};
+        }
+        var title = item.title,
+          subtitle = item.subtitle,
+          image = item.image;
+        // Assigned into an annotated local rather than returned as a literal: a
+        // computed key widens `status` to `string`.
+        var res = {};
+        res[sourcePath] = {
+          status: "success",
+          data: {
+            self: {
+              title: title,
+              subtitle: subtitle,
+              image: image
+            }
+          }
+        };
+        return res;
+      } catch (e) {
+        var _res = {};
+        _res[sourcePath] = {
+          status: "error",
+          message: e instanceof Error ? e.message : "Unknown error"
+        };
+        return _res;
+      }
+    }
     /**
      * 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;
@@ -423,7 +508,9 @@ var Schema = /*#__PURE__*/function () {
      * `executePreview` reifies an {@link ArrayPreview} / {@link RecordPreview}
      * from item-level declarations.
      */
-    function executePreviewItem(src) {
+  }, {
+    key: "executePreviewItem",
+    value: function executePreviewItem(src) {
       return null;
     }
     /**
@@ -504,6 +591,241 @@ var Schema = /*#__PURE__*/function () {
 
 // TODO: SourceError<"Could not determine type of Schema">
 
+function ownKeys(e, r) {
+  var t = Object.keys(e);
+  if (Object.getOwnPropertySymbols) {
+    var o = Object.getOwnPropertySymbols(e);
+    r && (o = o.filter(function (r) {
+      return Object.getOwnPropertyDescriptor(e, r).enumerable;
+    })), t.push.apply(t, o);
+  }
+  return t;
+}
+function _objectSpread2(e) {
+  for (var r = 1; r < arguments.length; r++) {
+    var t = null != arguments[r] ? arguments[r] : {};
+    r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
+      _defineProperty(e, r, t[r]);
+    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
+      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+    });
+  }
+  return e;
+}
+
+/**
+ * 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
+ * reference — which is everywhere the value is NAVIGABLE to rather than open.
+ * It is never how the field itself is edited: that is a RENDER (`render.ts`),
+ * which applies only when you are looking at the field. The two do not
+ * intersect — a schema can carry both, and each is read in its own places.
+ *
+ * A preview is declared on the schema of the VALUE being previewed:
+ *
+ * ```ts
+ * const author = s.object({ name: s.string() })
+ *   .preview(({ val }) => ({ title: val.name }));
+ * const authors = s.array(author);
+ * ```
+ *
+ * The container reifies its rows by running each ITEM's preview closure — see
+ * {@link ArrayPreview} / {@link RecordPreview}. (Previews used to be declared
+ * on the container instead; a `.preview` on an array/record now previews the
+ * array/record itself as a value, for when IT is the item of something.)
+ */
+/**
+ * What a preview shows for one value: the user's `preview` callback returns
+ * this, and the Studio draws a row from it.
+ *
+ * NB: {@link ArrayPreview} / {@link RecordPreview} name the DATA a container
+ * previews with. The Studio also has React components called `ArrayPreview` /
+ * `RecordPreview` (the fallback rendering of an array / record field, part of
+ * the `<Type>Preview` convention in `components/Preview.tsx`). They do not
+ * collide today because no file needs both - if one ever does, alias this type
+ * at the import rather than renaming that convention.
+ */
+
+/**
+ * What `.preview(...)` takes, on every schema: the value's own source in, a
+ * {@link PreviewItem} out. `NonNullable` because a container skips null items
+ * rather than previewing them.
+ *
+ * Declared through method syntax deliberately (the same bivariance shape
+ * React's event handler types use): `nullable()` copies a schema's closure
+ * into the `Src | null` variant of the same class, and with a plain function
+ * type the checker cannot see that `NonNullable<Src | null>` IS
+ * `NonNullable<Src>` while `Src` is still a type parameter — every schema's
+ * `nullable()` would need a cast instead.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+function mergePreviewInto(target, incoming) {
+  for (var keyS in incoming) {
+    var key = keyS;
+    var next = incoming[key];
+    var current = target[key];
+    if (current === undefined || next.status === "error") {
+      target[key] = next;
+      continue;
+    }
+    if (current.status === "error" || next.status === "loading") {
+      continue;
+    }
+    if (current.status === "loading") {
+      target[key] = next;
+      continue;
+    }
+    target[key] = {
+      status: "success",
+      data: _objectSpread2(_objectSpread2({}, current.data), next.data)
+    };
+  }
+}
+
+/**
+ * Which paths a preview is being computed FOR.
+ *
+ * `executePreview` takes a whole module, so one request has always walked every
+ * node in it and run every `preview` closure - for `handboka`, with `preview` at
+ * two nested array levels, that is every chapter and every section to serve one
+ * visible row. A scope is what makes the walk proportional to what is being
+ * looked at instead of to the project.
+ *
+ * Two questions, because a container and its items need different answers:
+ *
+ * - {@link PreviewScope.wants} - is a preview AT this exact path wanted? A
+ *   container answers `true` here when the whole of it is being shown, and its
+ *   preview is then computed in full.
+ * - {@link PreviewScope.wantsUnder} - could anything at or below this path be
+ *   wanted? Recursion is pruned where this is `false`, and a container whose own
+ *   path is not wanted but which has wanted descendants previews a WINDOW: only
+ *   the items that were asked for. That is the case a single visible row is, and
+ *   it is why {@link ArrayPreview} carries indices.
+ *
+ * Absent scope means the whole module, which is what every existing caller
+ * passes and what every existing caller got.
+ */
+
+/**
+ * A scope covering exactly `paths` and their subtrees.
+ *
+ * Compares SEGMENTS rather than string prefixes. A source path's module path is
+ * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
+ * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
+ * dot or a quote - `"title"` against `"titles"` being the cheapest example.
+ * Segments are parsed once here, not per comparison.
+ */
+function previewScope(paths) {
+  var wanted = paths.map(function (path) {
+    var _splitModuleFilePathA = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA2 = _slicedToArray(_splitModuleFilePathA, 2),
+      moduleFilePath = _splitModuleFilePathA2[0],
+      modulePath = _splitModuleFilePathA2[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  });
+  var parse = function parse(path) {
+    var _splitModuleFilePathA3 = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA4 = _slicedToArray(_splitModuleFilePathA3, 2),
+      moduleFilePath = _splitModuleFilePathA4[0],
+      modulePath = _splitModuleFilePathA4[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  };
+  var isPrefix = function isPrefix(prefix, of) {
+    if (prefix.length > of.length) return false;
+    for (var i = 0; i < prefix.length; i++) {
+      if (prefix[i] !== of[i]) return false;
+    }
+    return true;
+  };
+  return {
+    wants: function wants(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && entry.segments.length === at.segments.length && isPrefix(entry.segments, at.segments);
+      });
+    },
+    wantsUnder: function wantsUnder(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && (
+        // Either direction: a wanted path below `path` means recurse into it,
+        // and a wanted path ABOVE it means the whole subtree was asked for.
+        isPrefix(at.segments, entry.segments) || isPrefix(entry.segments, at.segments));
+      });
+    }
+  };
+}
+
+// TODO: improve this so that we do not get RawString and string, only string. Are there other things?
+
 // Identity symbols are registered in the global Symbol registry so that
 // multiple bundled copies of @valbuild/core (e.g. the editor SPA bundle vs.
 // the host Next.js bundle) resolve to the same Symbol instance. Without
@@ -616,28 +938,6 @@ function unsafeCreateSourcePath(path, itemKey) {
   return "".concat(path).concat(Internal.ModuleFilePathSep).concat(JSON.stringify(itemKey));
 }
 
-function ownKeys(e, r) {
-  var t = Object.keys(e);
-  if (Object.getOwnPropertySymbols) {
-    var o = Object.getOwnPropertySymbols(e);
-    r && (o = o.filter(function (r) {
-      return Object.getOwnPropertyDescriptor(e, r).enumerable;
-    })), t.push.apply(t, o);
-  }
-  return t;
-}
-function _objectSpread2(e) {
-  for (var r = 1; r < arguments.length; r++) {
-    var t = null != arguments[r] ? arguments[r] : {};
-    r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
-      _defineProperty(e, r, t[r]);
-    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
-      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
-    });
-  }
-  return e;
-}
-
 var StringSchema = /*#__PURE__*/function (_Schema) {
   function StringSchema(options) {
     var _this;
@@ -668,10 +968,13 @@ var StringSchema = /*#__PURE__*/function (_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.
    *
@@ -1008,11 +1311,6 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      * is a `render`, which travels in the serialized schema instead of through
      * this pipeline.
      */
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var string = function string(options) {
@@ -1045,10 +1343,13 @@ var ObjectSchema = /*#__PURE__*/function (_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.
    *
@@ -1360,7 +1661,7 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -1377,11 +1678,14 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.items[_key3]["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key4 = keyS;
-          res[_key4] = itemResult[_key4];
-        }
+        mergePreviewInto(res, this.items[_key3]["executePreview"](subPath, itemSrc, scope));
+      }
+      // An object reifies no rows of its own, so the only thing it adds is what
+      // IT is called — which nothing else can supply for a field of an object.
+      // Its own items are NOT rows, so the flag stops here rather than travelling
+      // down with the recursion above.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -1422,10 +1726,13 @@ var ArraySchema = /*#__PURE__*/function (_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.
    *
@@ -1584,7 +1891,7 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -1599,11 +1906,10 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.item["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key = keyS;
-          res[_key] = itemResult[_key];
-        }
+        mergePreviewInto(res,
+        // `true`: this item is a ROW, and its preview is the closure reified
+        // into `rows` below. See `executePreview` on `Schema`.
+        this.item["executePreview"](subPath, itemSrc, scope, true));
       }
       // The rows preview comes from the ITEM schema's own `preview` — the
       // container just runs it per row. Asked as a fact rather than by running
@@ -1650,13 +1956,29 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
             };
           }
         }
-        res[sourcePath] = {
+        var rows = {};
+        rows[sourcePath] = {
           status: "success",
           data: {
-            parent: "array",
-            items: items
+            rows: {
+              parent: "array",
+              items: items
+            }
           }
         };
+        mergePreviewInto(res, rows);
+      }
+      // ...and what the LIST ITSELF is called, which is a different closure on a
+      // different schema: `s.array(section.preview(...)).preview(...)` previews
+      // its rows AND names itself for when it is nested in something. Merged
+      // rather than assigned, or one of the two would win. See `PreviewNode`.
+      //
+      // Unless this list is itself a ROW of an outer array or record, which has
+      // already run this very closure to reify it — a container both PASSES the
+      // flag to its items and RECEIVES it as one, and honouring only the first
+      // half ran `s.array(s.array(x).preview(...))`'s closure twice per row.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -1759,10 +2081,13 @@ var LiteralSchema = /*#__PURE__*/function (_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.
    *
@@ -1951,11 +2276,6 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var literal = function literal(value) {
@@ -2011,10 +2331,13 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_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.
    *
@@ -2467,7 +2790,7 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -2492,10 +2815,16 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
         return false;
       });
       if (thisSchema) {
-        var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
-        for (var keyS in itemResult) {
-          var _key2 = keyS;
-          res[_key2] = itemResult[_key2];
+        // The variant owns the path — see the note on `executeCustomValidateAt`.
+        // It contributes a `self` of its own here; the union's comes second and
+        // wins, because `executePreviewItem` already encodes the precedence (the
+        // union's own closure if it has one, else the matched variant's) and
+        // there must not be a second copy of that rule.
+        // The variant SHARES this path, so the flag passes straight through: a
+        // union that is a row is a variant that is a row.
+        mergePreviewInto(res, thisSchema["executePreview"](sourcePath, src, scope, selfIsReifiedByParent));
+        if (!selfIsReifiedByParent) {
+          mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
         }
         return res;
       }
@@ -2508,8 +2837,8 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
   }]);
 }(Schema);
 var discriminatedUnion = function discriminatedUnion(key) {
-  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key3 = 1; _key3 < _len; _key3++) {
-    objects[_key3 - 1] = arguments[_key3];
+  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key2 = 1; _key2 < _len; _key2++) {
+    objects[_key2 - 1] = arguments[_key2];
   }
   return new DiscriminatedUnionSchema(key, objects);
 };
@@ -3486,10 +3815,13 @@ var ImageSchema = /*#__PURE__*/function (_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.
    *
@@ -3870,11 +4202,6 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -3930,10 +4257,13 @@ var RouteSchema = /*#__PURE__*/function (_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.
    *
@@ -4162,11 +4492,6 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var route = function route(options) {
@@ -4199,10 +4524,13 @@ var RichTextSchema = /*#__PURE__*/function (_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.
    *
@@ -4848,11 +5176,6 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var richtext = function richtext(options) {
@@ -5367,10 +5690,13 @@ var RecordSchema = /*#__PURE__*/function (_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.
    *
@@ -6163,7 +6489,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -6188,11 +6514,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.item["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key3 = keyS;
-          res[_key3] = itemResult[_key3];
-        }
+        mergePreviewInto(res,
+        // `true`: this item is a ROW, and its preview is the closure reified
+        // into `rows` below. See `executePreview` on `Schema`.
+        this.item["executePreview"](subPath, itemSrc, scope, true));
       }
       // The entries preview comes from the ITEM schema's own `preview` — the
       // container just runs it per entry. Asked as a fact rather than by running
@@ -6204,7 +6529,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         var items = [];
         for (var _i2 = 0, _Object$entries = Object.entries(src); _i2 < _Object$entries.length; _i2++) {
           var _Object$entries$_i = _slicedToArray(_Object$entries[_i2], 2),
-            _key4 = _Object$entries$_i[0],
+            _key3 = _Object$entries$_i[0],
             val = _Object$entries$_i[1];
           if (isJson(val)) {
             continue; // as above: nothing to select from an un-loaded entry
@@ -6212,7 +6537,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           if (val === null || val === undefined) {
             continue;
           }
-          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key4))) {
+          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key3))) {
             continue;
           }
           // Per KEY, not per record: the closure is user code, and one entry whose
@@ -6224,26 +6549,37 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
               var title = _item.title,
                 subtitle = _item.subtitle,
                 image = _item.image;
-              items.push([_key4, {
+              items.push([_key3, {
                 title: title,
                 subtitle: subtitle,
                 image: image
               }]);
             }
           } catch (e) {
-            res[unsafeCreateSourcePath(sourcePath, _key4)] = {
+            res[unsafeCreateSourcePath(sourcePath, _key3)] = {
               status: "error",
               message: e instanceof Error ? e.message : "Unknown error"
             };
           }
         }
-        res[sourcePath] = {
+        var rows = {};
+        rows[sourcePath] = {
           status: "success",
           data: {
-            parent: "record",
-            items: items
+            rows: {
+              parent: "record",
+              items: items
+            }
           }
         };
+        mergePreviewInto(res, rows);
+      }
+      // ...and what the RECORD ITSELF is called — a different closure on a
+      // different schema. Skipped when this record is itself a ROW, whose
+      // closure the outer container has already run. See the same block in
+      // `array`, and `PreviewNode`.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -6368,6 +6704,16 @@ function record(keyOrSchema, schema) {
  * written without removing the key.
  */
 
+/**
+ * How the Studio behaves for the people editing this project.
+ *
+ * Not how it looks — that is {@link ThemeSettingsSource} — and not one person's
+ * own preferences, which stay in their browser. This is the project's word on
+ * what its editors are offered, which is why it is content: a team that has
+ * decided something about the way they work should not need a developer and a
+ * deploy to say so.
+ */
+
 /**
  * How the Studio looks in this project.
  *
@@ -6735,11 +7081,6 @@ var LocaleSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -6784,10 +7125,13 @@ var BooleanSchema = /*#__PURE__*/function (_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.
    *
@@ -6961,11 +7305,6 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var _boolean = function _boolean() {
@@ -7478,10 +7817,13 @@ var ColorSchema = /*#__PURE__*/function (_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.
    *
@@ -7705,11 +8047,6 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var color = function color(options) {
@@ -7760,10 +8097,13 @@ var EnumSchema = /*#__PURE__*/function (_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.
    *
@@ -7976,12 +8316,6 @@ var EnumSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      // A leaf: nothing below it to preview.
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -8321,7 +8655,7 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -8335,11 +8669,14 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.items[_key4]["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key5 = keyS;
-          res[_key5] = itemResult[_key5];
-        }
+        mergePreviewInto(res, this.items[_key4]["executePreview"](subPath, itemSrc, scope));
+      }
+      // An object reifies no rows of its own, so the only thing it adds is what
+      // IT is called — which nothing else can supply for a field of an object.
+      // Its own items are NOT rows, so the flag stops here rather than travelling
+      // down with the recursion above.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -8402,6 +8739,9 @@ function settings() {
         dir: THEME_LOGO_DIRECTORY
       }).nullable().describe("The project's own mark, shown where Val's is in the Studio. A square-ish mark rather than a wordmark: the slot is 32px wide.")
     }),
+    studio: new SettingsSchema({
+      tour: _boolean().nullable().describe("Whether editors are offered the guided tour of the Studio. Unset means yes. Off hides the offer for everyone on this project — the tour stays in Quick actions for anyone who wants it.")
+    }),
     locales: new SettingsSchema({
       // Nullable because the source type is, and because the Studio writes
       // `null` for every sibling the first time a section is created.
@@ -8579,10 +8919,25 @@ function resolvePath(path, valModule, schema) {
         if (_typeof(resolvedSource) !== "object" && !Array.isArray(resolvedSource)) {
           throw Error("Schema type error: expected source to be type of record, but got ".concat(_typeof(resolvedSource)));
         }
-        if (!resolvedSource[part]) {
+        // PRESENCE, not truthiness. An entry that exists and is falsy is an
+        // entry: `null` for a declared key nobody has written yet, but also `""`,
+        // `0` and `false` in any record at all. Testing the value made every one
+        // of those report as a key the record does not have, so nothing could
+        // resolve them — not the Studio, not the language server, not a fix.
+        //
+        // A record source that is itself `null` keeps resolving as `null`, one
+        // part per level, the way the object branch below does: the path still
+        // names a real place in the schema, and the caller wants the schema
+        // there in order to say that nothing is written yet.
+        //
+        // `hasOwnProperty`, never `in`: `in` walks the prototype chain, so
+        // `"toString"` would resolve on every record and hand back
+        // `Object.prototype.toString` as if it were Source. Same reason
+        // `patch/json.ts` guards every key it reads.
+        if (resolvedSource !== null && !Object.prototype.hasOwnProperty.call(resolvedSource, part)) {
           throw Error("Invalid path: record source did not have key ".concat(part, " from path: ").concat(path));
         }
-        resolvedSource = resolvedSource[part];
+        resolvedSource = resolvedSource === null ? resolvedSource : resolvedSource[part];
         resolvedSchema = resolvedSchema instanceof RecordSchema ? (_resolvedSchema2 = resolvedSchema) === null || _resolvedSchema2 === void 0 ? void 0 : _resolvedSchema2["item"] : resolvedSchema.item;
         // A `.jsonValues()` entry value is a lazily-loaded JsonSource marker. We
         // can resolve the entry itself (schema is now `item`), but we cannot
@@ -8784,7 +9139,15 @@ function safeResolvePath(path, valModule, schema) {
             }
           };
         }
-        if (resolvedSource[part] === undefined) {
+        // A `null` record keeps resolving as `null`, as the object branch below
+        // does — see the same note in `resolvePath`. Without it, indexing `null`
+        // threw a TypeError out of the function whose whole point is not to
+        // throw.
+        //
+        // Own properties only. Testing `resolvedSource[part] === undefined` let
+        // an inherited name through — `"toString"` is not undefined on any
+        // object — so the walk continued into `Object.prototype`.
+        if (resolvedSource !== null && !Object.prototype.hasOwnProperty.call(resolvedSource, part)) {
           return {
             v: {
               status: "source-undefined",
@@ -8794,7 +9157,7 @@ function safeResolvePath(path, valModule, schema) {
             }
           };
         }
-        resolvedSource = resolvedSource[part];
+        resolvedSource = resolvedSource === null ? resolvedSource : resolvedSource[part];
         resolvedSchema = resolvedSchema instanceof RecordSchema ? (_resolvedSchema4 = resolvedSchema) === null || _resolvedSchema4 === void 0 ? void 0 : _resolvedSchema4["item"] : resolvedSchema.item;
         // jsonValues entry: cannot descend deeper until the backing `*.val.json`
         // content is loaded into the source tree.
@@ -9053,10 +9416,13 @@ var NumberSchema = /*#__PURE__*/function (_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.
    *
@@ -9280,11 +9646,6 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var number = function number(options) {
@@ -9397,10 +9758,13 @@ var KeyOfSchema = /*#__PURE__*/function (_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.
    *
@@ -9682,11 +10046,6 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var keyOf = function keyOf(valModule) {
@@ -9743,10 +10102,13 @@ var FileSchema = /*#__PURE__*/function (_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.
    *
@@ -10087,11 +10449,6 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -10184,10 +10541,13 @@ var DateSchema = /*#__PURE__*/function (_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.
    *
@@ -10432,11 +10792,6 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var date = function date(options) {
@@ -10469,10 +10824,13 @@ var DateTimeSchema = /*#__PURE__*/function (_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.
    *
@@ -10772,11 +11130,6 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var datetime = function datetime(options) {
@@ -10823,10 +11176,13 @@ var CodeSchema = /*#__PURE__*/function (_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.
    *
@@ -11017,11 +11373,6 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var code = function code(options) {
@@ -12595,142 +12946,31 @@ function deserializeSchemaImpl(serialized) {
 }
 
 /**
- * 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
- * reference — which is everywhere the value is NAVIGABLE to rather than open.
- * It is never how the field itself is edited: that is a RENDER (`render.ts`),
- * which applies only when you are looking at the field. The two do not
- * intersect — a schema can carry both, and each is read in its own places.
- *
- * A preview is declared on the schema of the VALUE being previewed:
- *
- * ```ts
- * const author = s.object({ name: s.string() })
- *   .preview(({ val }) => ({ title: val.name }));
- * const authors = s.array(author);
- * ```
- *
- * The container reifies its rows by running each ITEM's preview closure — see
- * {@link ArrayPreview} / {@link RecordPreview}. (Previews used to be declared
- * on the container instead; a `.preview` on an array/record now previews the
- * array/record itself as a value, for when IT is the item of something.)
- */
-/**
- * What a preview shows for one value: the user's `preview` callback returns
- * this, and the Studio draws a row from it.
- *
- * NB: {@link ArrayPreview} / {@link RecordPreview} name the DATA a container
- * previews with. The Studio also has React components called `ArrayPreview` /
- * `RecordPreview` (the fallback rendering of an array / record field, part of
- * the `<Type>Preview` convention in `components/Preview.tsx`). They do not
- * collide today because no file needs both - if one ever does, alias this type
- * at the import rather than renaming that convention.
- */
-
-/**
- * What `.preview(...)` takes, on every schema: the value's own source in, a
- * {@link PreviewItem} out. `NonNullable` because a container skips null items
- * rather than previewing them.
+ * THE RULE, and the only sentence that needs to be remembered:
  *
- * Declared through method syntax deliberately (the same bivariance shape
- * React's event handler types use): `nullable()` copies a schema's closure
- * into the `Src | null` variant of the same class, and with a plain function
- * type the checker cannot see that `NonNullable<Src | null>` IS
- * `NonNullable<Src>` while `Src` is still a type parameter — every schema's
- * `nullable()` would need a cast instead.
- */
-
-/**
- * Main preview type.
+ *   **`.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.**
  *
- * 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.
- */
-
-/**
- * Which paths a preview is being computed FOR.
- *
- * `executePreview` takes a whole module, so one request has always walked every
- * node in it and run every `preview` closure - for `handboka`, with `preview` at
- * two nested array levels, that is every chapter and every section to serve one
- * visible row. A scope is what makes the walk proportional to what is being
- * looked at instead of to the project.
+ * 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.
  *
- * Two questions, because a container and its items need different answers:
- *
- * - {@link PreviewScope.wants} - is a preview AT this exact path wanted? A
- *   container answers `true` here when the whole of it is being shown, and its
- *   preview is then computed in full.
- * - {@link PreviewScope.wantsUnder} - could anything at or below this path be
- *   wanted? Recursion is pruned where this is `false`, and a container whose own
- *   path is not wanted but which has wanted descendants previews a WINDOW: only
- *   the items that were asked for. That is the case a single visible row is, and
- *   it is why {@link ArrayPreview} carries indices.
+ * 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.
  *
- * Absent scope means the whole module, which is what every existing caller
- * passes and what every existing caller got.
+ * None of the three substitutes for another: a field with a perfect
+ * description still previews as `#3` until someone writes the preview.
  */
-
-/**
- * A scope covering exactly `paths` and their subtrees.
- *
- * Compares SEGMENTS rather than string prefixes. A source path's module path is
- * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
- * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
- * dot or a quote - `"title"` against `"titles"` being the cheapest example.
- * Segments are parsed once here, not per comparison.
- */
-function previewScope(paths) {
-  var wanted = paths.map(function (path) {
-    var _splitModuleFilePathA = splitModuleFilePathAndModulePath(path),
-      _splitModuleFilePathA2 = _slicedToArray(_splitModuleFilePathA, 2),
-      moduleFilePath = _splitModuleFilePathA2[0],
-      modulePath = _splitModuleFilePathA2[1];
-    return {
-      moduleFilePath: moduleFilePath,
-      segments: modulePath === "" ? [] : splitModulePath(modulePath)
-    };
-  });
-  var parse = function parse(path) {
-    var _splitModuleFilePathA3 = splitModuleFilePathAndModulePath(path),
-      _splitModuleFilePathA4 = _slicedToArray(_splitModuleFilePathA3, 2),
-      moduleFilePath = _splitModuleFilePathA4[0],
-      modulePath = _splitModuleFilePathA4[1];
-    return {
-      moduleFilePath: moduleFilePath,
-      segments: modulePath === "" ? [] : splitModulePath(modulePath)
-    };
-  };
-  var isPrefix = function isPrefix(prefix, of) {
-    if (prefix.length > of.length) return false;
-    for (var i = 0; i < prefix.length; i++) {
-      if (prefix[i] !== of[i]) return false;
-    }
-    return true;
-  };
-  return {
-    wants: function wants(path) {
-      var at = parse(path);
-      return wanted.some(function (entry) {
-        return entry.moduleFilePath === at.moduleFilePath && entry.segments.length === at.segments.length && isPrefix(entry.segments, at.segments);
-      });
-    },
-    wantsUnder: function wantsUnder(path) {
-      var at = parse(path);
-      return wanted.some(function (entry) {
-        return entry.moduleFilePath === at.moduleFilePath && (
-        // Either direction: a wanted path below `path` means recurse into it,
-        // and a wanted path ABOVE it means the whole subtree was asked for.
-        isPrefix(at.segments, entry.segments) || isPrefix(entry.segments, at.segments));
-      });
-    }
-  };
-}
-
-// TODO: improve this so that we do not get RawString and string, only string. Are there other things?
-
 /**
  * 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
@@ -13247,7 +13487,7 @@ function isPageRouter(routerId) {
 
 var corePackageJson = {
 	name: "@valbuild/core",
-	version: "0.129.0",
+	version: "0.130.0",
 	"private": false,
 	description: "Val - supercharged hard-coded content",
 	repository: {