@valbuild/core 0.129.0 → 0.134.0

package/dist/{index-21fd16b1.cjs.dev.js → index-85a2ffba.cjs.dev.js}

@@ -413,8 +413,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;
@@ -425,7 +510,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;
     }
     /**
@@ -506,6 +593,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
@@ -618,28 +940,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;
@@ -670,10 +970,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.
    *
@@ -1010,11 +1313,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) {
@@ -1047,10 +1345,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.
    *
@@ -1362,7 +1663,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;
@@ -1379,11 +1680,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;
     }
@@ -1424,10 +1728,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.
    *
@@ -1586,7 +1893,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;
@@ -1601,11 +1908,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
@@ -1652,13 +1958,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;
     }
@@ -1761,10 +2083,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.
    *
@@ -1953,11 +2278,6 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var literal = function literal(value) {
@@ -2013,10 +2333,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.
    *
@@ -2469,7 +2792,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;
@@ -2494,10 +2817,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;
       }
@@ -2510,8 +2839,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);
 };
@@ -3488,10 +3817,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.
    *
@@ -3872,11 +4204,6 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -3932,10 +4259,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.
    *
@@ -4164,11 +4494,6 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var route = function route(options) {
@@ -4201,10 +4526,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.
    *
@@ -4850,11 +5178,6 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var richtext = function richtext(options) {
@@ -5369,10 +5692,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.
    *
@@ -6165,7 +6491,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;
@@ -6190,11 +6516,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
@@ -6206,7 +6531,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
@@ -6214,7 +6539,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
@@ -6226,26 +6551,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;
     }
@@ -6370,6 +6706,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.
  *
@@ -6737,11 +7083,6 @@ var LocaleSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -6786,10 +7127,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.
    *
@@ -6963,11 +7307,6 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var _boolean = function _boolean() {
@@ -7480,10 +7819,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.
    *
@@ -7707,11 +8049,6 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var color = function color(options) {
@@ -7762,10 +8099,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.
    *
@@ -7978,12 +8318,6 @@ var EnumSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      // A leaf: nothing below it to preview.
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -8323,7 +8657,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;
@@ -8337,11 +8671,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;
     }
@@ -8404,6 +8741,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.
@@ -8453,6 +8793,317 @@ function localesSectionErrors(src) {
   return errors;
 }
 
+/**
+ * Type-level-only slot carrying the SOURCE TYPE of the module a view names.
+ *
+ * Optional, and that is what makes the marker writable: `{ view: "/foo.val.ts" }`
+ * is a plain literal, and an optional symbol-keyed property costs the author
+ * nothing to satisfy. It exists so the read side can say WHAT is behind the
+ * pointer — `ValView<FooSrc>` rather than `ValView<unknown>` — without the
+ * author having to write a type they do not have.
+ */
+
+/**
+ * The source of a view field: a pointer to another module, and nothing else.
+ *
+ * Written as a plain object, like media and for the same reason — the same
+ * value has to work in a `.val.ts` and in a `*.val.json` entry, and a literal
+ * survives the static extraction that a constructor call does not. See
+ * `architecture/media.md`.
+ *
+ * `Id` is the target's module file path as a LITERAL type, inferred from the
+ * module handed to `s.view(...)`. So the path autocompletes at the call site,
+ * and a source naming a different module than its schema does is a type error.
+ *
+ * Nothing decides "this is a view" by looking at the value; the SCHEMA does
+ * (`type === "view"`). {@link isValViewSource} exists for the few places that have
+ * a value and no schema, and is not the normal way to ask.
+ */
+
+/**
+ * Is this value shaped like a view marker?
+ *
+ * A shape test, not an identity: `view` is a reserved object key
+ * (`ObjectSchemaProps`), so no ordinary object source can take this shape — but
+ * hand-written JSON can, which is why validation checks the value against the
+ * schema rather than trusting it.
+ */
+function isValViewSource(value) {
+  return _typeof(value) === "object" && value !== null && !Array.isArray(value) && "view" in value && typeof value.view === "string";
+}
+
+/** The source type of the module a selector points at. */
+
+/**
+ * A field that points at ANOTHER module, for the Val editor's benefit.
+ *
+ * The source is `{ view: "/other.val.ts" }` — a pointer, and nothing else. The
+ * module it names keeps its own source, its own patches, its own validation and
+ * its own address; this field puts a row on THIS module's screen that an editor
+ * clicks through to it.
+ *
+ * Two type parameters, each earning its place:
+ *
+ * - `Id` — the target's module file path as a literal, so the author writes
+ *   `{ view: "/other.val.ts" }` with autocomplete, and naming a different module
+ *   than the schema does is a type error rather than a validation error.
+ * - `T` — the target's source type, carried on a phantom slot so the READ side
+ *   can say `ValView<T>` rather than `ValView<unknown>`. Nothing reads it yet;
+ *   it is here so that resolving a view through `useVal` can be added without
+ *   changing what is stored.
+ */
+var ValViewSchema = /*#__PURE__*/function (_Schema) {
+  function ValViewSchema(moduleFilePath) {
+    var _this;
+    var valModule = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : undefined;
+    var isReadonly = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+    var isHidden = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+    var description = arguments.length > 4 ? arguments[4] : undefined;
+    var renderInput = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : null;
+    _classCallCheck(this, ValViewSchema);
+    _this = _callSuper(this, ValViewSchema);
+    _this.moduleFilePath = moduleFilePath;
+    _this.valModule = valModule;
+    _this.isReadonly = isReadonly;
+    _this.isHidden = isHidden;
+    _this.description = description;
+    _this.renderInput = renderInput;
+    return _this;
+  }
+
+  /**
+   * Describe this field.
+   *
+   * Shown next to the field's label in the Val editor — here, the place to say
+   * WHY the other module is on this screen, since an editor who follows the row
+   * is about to change content that other pages use too.
+   *
+   * @example
+   * import otherVal from "./other.val"; // another module
+   * const schema = s.object({
+   *   shared: s.view(otherVal).describe("Shared by every page"),
+   *   title: s.string(),
+   * });
+   * export default c.define("/example.val.ts", schema, {
+   *   shared: { view: "/other.val.ts" },
+   *   title: "Hello",
+   * });
+   */
+  _inherits(ValViewSchema, _Schema);
+  return _createClass(ValViewSchema, [{
+    key: "describe",
+    value: function describe(description) {
+      return new ValViewSchema(this.moduleFilePath, this.valModule, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput);
+    }
+
+    /**
+     * The stored pointer must name the module the SCHEMA names.
+     *
+     * It cannot disagree in a `.val.ts` — the source type is the literal path, so
+     * a mismatch does not compile. It can disagree in hand-written JSON (a
+     * `.jsonValues()` entry, an external record), which is what this is for.
+     */
+  }, {
+    key: "executeValidate",
+    value: function executeValidate(path, src) {
+      if (!isValViewSource(src)) {
+        return _defineProperty({}, path, [{
+          message: "Expected a view pointer ({ view: \"".concat(this.moduleFilePath, "\" }), got '").concat(src === null ? "null" : _typeof(src), "'"),
+          value: src,
+          fixes: ["view:check-module"]
+        }]);
+      }
+      if (src.view !== this.moduleFilePath) {
+        return _defineProperty({}, path, [{
+          message: "This view points at '".concat(src.view, "', but its schema says '").concat(this.moduleFilePath, "'"),
+          value: src,
+          fixes: ["view:check-module"]
+        }]);
+      }
+      return false;
+    }
+  }, {
+    key: "executeCustomValidateAt",
+    value: function executeCustomValidateAt(_path, _src) {
+      return [];
+    }
+  }, {
+    key: "executeAssert",
+    value: function executeAssert(path, src) {
+      if (isValViewSource(src)) {
+        return {
+          success: true,
+          data: src
+        };
+      }
+      return {
+        success: false,
+        errors: _defineProperty({}, path, [{
+          message: "Expected a view pointer ({ view: string }), got '".concat(src === null ? "null" : _typeof(src), "'"),
+          typeError: true
+        }])
+      };
+    }
+
+    /**
+     * Not available: a view points at a module, and `null` is not a module.
+     * Throws if called.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * // `s.view(otherVal).nullable()` throws — a view is never nullable.
+     * 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",
+     * });
+     */
+  }, {
+    key: "nullable",
+    value: function nullable() {
+      throw new Error("s.view() cannot be nullable: it points at a module");
+    }
+
+    /**
+     * Marks the row read-only.
+     *
+     * The view's OWN flag, and it says nothing about the module it names: that
+     * module has its own `readonly`, which is what governs editing once an
+     * editor is there. A view is a link rather than an editor, so this changes
+     * nothing about the row today — it exists because every schema has it, and
+     * because a view that renders its target inline would need it.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).readonly(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+  }, {
+    key: "readonly",
+    value: function readonly() {
+      var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new ValViewSchema(this.moduleFilePath, this.valModule, isReadonly, this.isHidden, this.description, this.renderInput);
+    }
+
+    /**
+     * Hide the ROW in the editor.
+     *
+     * The view's OWN flag, and it is the only thing that decides whether the row
+     * is drawn — a view whose TARGET is hidden is still shown, and still leads
+     * there. That is the point of it: a module that many modules `keyOf` into is
+     * noise in the nav and belongs on exactly one page, so it is hidden from the
+     * listing and reached through the view that puts it where it belongs.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).hidden(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+  }, {
+    key: "hidden",
+    value: function hidden() {
+      var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new ValViewSchema(this.moduleFilePath, this.valModule, this.isReadonly, isHidden, this.description, this.renderInput);
+    }
+
+    /**
+     * How this field is laid out in the editor. Static configuration, not a
+     * callback — see `render.ts`.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).render({ as: "inline" }),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+  }, {
+    key: "render",
+    value: function render(input) {
+      return new ValViewSchema(this.moduleFilePath, this.valModule, this.isReadonly, this.isHidden, this.description, input);
+    }
+  }, {
+    key: "executeSerialize",
+    value: function executeSerialize() {
+      var _this$renderInput;
+      return {
+        type: "view",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
+        opt: false,
+        moduleFilePath: this.moduleFilePath,
+        readonly: this.isReadonly,
+        hidden: this.isHidden,
+        description: this.description
+      };
+    }
+  }, {
+    key: "executePreview",
+    value: function executePreview() {
+      return {};
+    }
+  }]);
+}(Schema);
+
+/**
+ * Point at another module, so the Val editor shows a way into it from here.
+ *
+ * A view stores a pointer and nothing else: the module it names keeps its own
+ * source, patches, validation and address, and an editor reaches it by clicking
+ * through rather than by hunting for it. It is there so content that has to live
+ * in its own module — a `keyOf` target, shared settings, a route-keyed record —
+ * can still be found from the page it belongs to.
+ *
+ * Reading it in consuming code gives you a pointer with no fields on it. Read
+ * the module it names directly instead.
+ *
+ * @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",
+ * });
+ */
+var view = function view(valModule) {
+  var path = getValPath(valModule);
+  if (!path) {
+    throw new Error("s.view() must be given a Val module");
+  }
+  return new ValViewSchema(path, valModule);
+};
+
+/**
+ * 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.
+ */
+
+/** A module's own path, read back off its type. */
+
 /**
  * What may be WRITTEN as an external record's source, on top of the marker.
  *
@@ -8472,6 +9123,17 @@ function localesSectionErrors(src) {
 function define(id,
 // TODO: `/${string}`
 schema, source) {
+  // A module cannot BE a view of another module. `s.view()` stores nothing, so
+  // the module's whole source would be `undefined` — which type-checks, because
+  // `undefined` is a `SelectorSource`, and then fails everywhere downstream that
+  // expects a module to have source. A view is a field of a module, never the
+  // module. Thrown rather than typed: making the `schema` parameter conditional
+  // on T would put it in a non-inferable position and break inference for every
+  // other schema. `extractValModules` reports what this throws as a module
+  // error, which is where a developer will look.
+  if (schema instanceof ValViewSchema) {
+    throw Error("Cannot define '".concat(id, "' as a view: s.view() shows another module and stores nothing, so it cannot be a module's own schema. Put it in an s.object({ ... }) field instead."));
+  }
   return _defineProperty(_defineProperty(_defineProperty({}, GetSource, source), GetSchema, schema), Path, id);
 }
 function getSource(valModule) {
@@ -8581,10 +9243,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
@@ -8786,7 +9463,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",
@@ -8796,7 +9481,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.
@@ -9055,10 +9740,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.
    *
@@ -9282,11 +9970,6 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var number = function number(options) {
@@ -9399,10 +10082,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.
    *
@@ -9684,11 +10370,6 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var keyOf = function keyOf(valModule) {
@@ -9745,10 +10426,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.
    *
@@ -10089,11 +10773,6 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -10186,10 +10865,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.
    *
@@ -10434,11 +11116,6 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var date = function date(options) {
@@ -10471,10 +11148,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.
    *
@@ -10774,11 +11454,6 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var datetime = function datetime(options) {
@@ -10825,10 +11500,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.
    *
@@ -11019,11 +11697,6 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var code = function code(options) {
@@ -11150,6 +11823,7 @@ function initSchema() {
     image: image,
     literal: literal,
     keyOf: keyOf,
+    view: view,
     record: record,
     file: file,
     fileset: fileset,
@@ -11657,6 +12331,185 @@ function resolveSettingsModule(schemas) {
   };
 }
 
+/**
+ * Every module a schema points at with `s.view(...)`, at any depth.
+ *
+ * A GENERIC walk over the serialized schema rather than a switch over the
+ * container types, and that is deliberate: a schema can hold another schema in
+ * places an enumeration keeps forgetting — a richtext's `a` and `img` options
+ * each carry one, and a discriminated union's variants are an array of them.
+ * Missing a nesting site here means missing a cycle, and a missed cycle is the
+ * failure this check exists to prevent.
+ */
+function viewTargetsOf(schema) {
+  var targets = [];
+  var seen = new Set();
+  function walk(node) {
+    if (_typeof(node) !== "object" || node === null) {
+      return;
+    }
+    // A serialized schema is a tree, but guard anyway: this runs over data the
+    // walk does not own, and a cycle here would hang module extraction.
+    if (seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+    if (Array.isArray(node)) {
+      var _iterator = result._createForOfIteratorHelper(node),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var item = _step.value;
+          walk(item);
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return;
+    }
+    var record = node;
+    if (record["type"] === "view") {
+      var target = record["moduleFilePath"];
+      if (typeof target === "string") {
+        targets.push(target);
+      }
+      // A view schema holds nothing else worth walking.
+      return;
+    }
+    for (var _i = 0, _Object$values = Object.values(record); _i < _Object$values.length; _i++) {
+      var value = _Object$values[_i];
+      walk(value);
+    }
+  }
+  walk(schema);
+  return targets;
+}
+
+/**
+ * The cycles in a project's views: `A → B → A`, and `A → A`.
+ *
+ * Each cycle is returned once, as the modules in it in order, rotated so it
+ * starts at the lexicographically smallest — otherwise the same cycle would be
+ * reported once per module it passes through, worded differently each time.
+ */
+function findViewCycles(schemas) {
+  var edges = new Map();
+  for (var _i2 = 0, _Object$entries = Object.entries(schemas); _i2 < _Object$entries.length; _i2++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i2], 2),
+      moduleFilePath = _Object$entries$_i[0],
+      schema = _Object$entries$_i[1];
+    edges.set(moduleFilePath, viewTargetsOf(schema));
+  }
+  var cycles = [];
+  var found = new Set();
+  var done = new Set();
+  var stack = [];
+  var onStack = new Set();
+  function visit(moduleFilePath) {
+    var _edges$get;
+    if (done.has(moduleFilePath)) {
+      return;
+    }
+    if (onStack.has(moduleFilePath)) {
+      var cycle = stack.slice(stack.indexOf(moduleFilePath));
+      var key = canonical(cycle);
+      if (!found.has(key)) {
+        found.add(key);
+        cycles.push(rotate(cycle));
+      }
+      return;
+    }
+    stack.push(moduleFilePath);
+    onStack.add(moduleFilePath);
+    var _iterator2 = result._createForOfIteratorHelper((_edges$get = edges.get(moduleFilePath)) !== null && _edges$get !== void 0 ? _edges$get : []),
+      _step2;
+    try {
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        var target = _step2.value;
+        // A target that is not a module of this project is a different error —
+        // the view names something that does not exist — and is reported where
+        // the field is, not here.
+        if (edges.has(target)) {
+          visit(target);
+        }
+      }
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    stack.pop();
+    onStack["delete"](moduleFilePath);
+    done.add(moduleFilePath);
+  }
+  var _iterator3 = result._createForOfIteratorHelper(edges.keys()),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var _moduleFilePath = _step3.value;
+      visit(_moduleFilePath);
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  return cycles;
+}
+function rotate(cycle) {
+  var at = 0;
+  for (var i = 1; i < cycle.length; i++) {
+    if (cycle[i] < cycle[at]) {
+      at = i;
+    }
+  }
+  return [].concat(_toConsumableArray(cycle.slice(at)), _toConsumableArray(cycle.slice(0, at)));
+}
+function canonical(cycle) {
+  return rotate(cycle).join(" -> ");
+}
+
+/**
+ * A cycle of views, as one error per module in it.
+ *
+ * Per module rather than once, because a developer opens ONE of them and the
+ * error has to be there when they do. Every copy names the whole cycle, so it
+ * reads the same wherever it is found.
+ */
+function viewCycleErrors(schemas) {
+  var errors = [];
+  var _iterator4 = result._createForOfIteratorHelper(findViewCycles(schemas)),
+    _step4;
+  try {
+    for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+      var cycle = _step4.value;
+      var described = [].concat(_toConsumableArray(cycle), [cycle[0]]).join(" -> ");
+      var _iterator5 = result._createForOfIteratorHelper(cycle),
+        _step5;
+      try {
+        for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+          var moduleFilePath = _step5.value;
+          errors.push({
+            path: moduleFilePath,
+            message: cycle.length === 1 ? "s.view() cycle: '".concat(moduleFilePath, "' views itself. A view must point at another module.") : "s.view() cycle: ".concat(described, ". Views may not form a cycle.")
+          });
+        }
+      } catch (err) {
+        _iterator5.e(err);
+      } finally {
+        _iterator5.f();
+      }
+    }
+  } catch (err) {
+    _iterator4.e(err);
+  } finally {
+    _iterator4.f();
+  }
+  return errors;
+}
+
 // Lazily constructed: this module is also evaluated inside the `vm` sandbox
 // used by loadValModules (when user val modules import @valbuild/core), and
 // that sandbox has no `TextEncoder` global. `hash()` is never called from
@@ -11824,7 +12677,7 @@ function extractValModules(_x) {
 }
 function _extractValModules() {
   _extractValModules = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(valModules) {
-    var moduleErrors, addModuleError, sources, schemas, serializedSchemas, shaEntries, moduleIdx, module, at, value, path, schema, source, serializedSchema, pathM, _iterator2, _step2, error, _t, _t2;
+    var moduleErrors, addModuleError, sources, schemas, serializedSchemas, shaEntries, moduleIdx, module, at, value, path, schema, source, serializedSchema, pathM, _iterator2, _step2, error, _iterator3, _step3, _error, _t, _t2;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.p = _context.n) {
         case 0:
@@ -11977,11 +12830,26 @@ function _extractValModules() {
               error = _step2.value;
               moduleErrors.push(error);
             }
+            // Same kind of rule, same reason it is here: a view cycle is a property of the
+            // whole set of schemas, so no single module can see it. Nothing further down
+            // catches it either — a view stores a pointer, not content, so there is no
+            // data cycle for a source walk to trip over.
           } catch (err) {
             _iterator2.e(err);
           } finally {
             _iterator2.f();
           }
+          _iterator3 = result._createForOfIteratorHelper(viewCycleErrors(serializedSchemas));
+          try {
+            for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+              _error = _step3.value;
+              moduleErrors.push(_error);
+            }
+          } catch (err) {
+            _iterator3.e(err);
+          } finally {
+            _iterator3.f();
+          }
           return _context.a(2, _objectSpread2(_objectSpread2({
             sources: sources,
             schemas: schemas,
@@ -12084,7 +12952,7 @@ function hasRemoteFileSchema(schema) {
     return false;
   } else if (schema.type === "boolean" ||
   // An enum's values are strings, so there is nothing to look inside.
-  schema.type === "enum" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" || schema.type === "locale") {
+  schema.type === "enum" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" || schema.type === "locale" || schema.type === "view") {
     return false;
   } else {
     var exhaustiveCheck = schema;
@@ -12159,7 +13027,9 @@ function hasMediaSchema(schema) {
   schema.type === "enum" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" || schema.type === "locale" ||
   // A settings module holds the assistant's configuration, not content, and
   // nothing in it is media.
-  schema.type === "settings") {
+  schema.type === "settings" ||
+  // A view shows another module; that module answers for its own media.
+  schema.type === "view") {
     return false;
   } else {
     // Same contract as above: adding a schema type without teaching this
@@ -12475,6 +13345,160 @@ function discriminatedUnionBranchOf(schema, tag) {
   return undefined;
 }
 
+/**
+ * Where a resolved view handle keeps the module it points at.
+ *
+ * A symbol, so it is invisible to `JSON.stringify`, `Object.keys`, the source
+ * SHAs and every walk that treats source as data — the handle still IS
+ * `{ view: "/foo.val.ts" }` everywhere that matters.
+ */
+var ViewTargetModule = Symbol["for"]("val/ViewTargetModule");
+
+/**
+ * A view's source with the module it names attached.
+ *
+ * `useVal(page.header)` needs the target's SOURCE and its SCHEMA, and the
+ * stored pointer has neither — it is a path. The app has no way to turn a path
+ * back into a module either: `val.modules` holds lazy `import()` thunks, and
+ * `<ValModulesClient>` is optional. So the module travels with the handle.
+ *
+ * Attached by the READ path (`stegaEncode`) rather than written into source,
+ * and that is the whole reason it works in draft mode: with an edit pending,
+ * the source comes from the overlay store as plain JSON that never went near a
+ * module. The schema is the module's own either way, so the encoder always has
+ * it to hand.
+ */
+
+/** Attach the module a view names to its pointer. */
+function createViewHandle(source, valModule) {
+  return _objectSpread2(_objectSpread2({}, source), {}, _defineProperty({}, ViewTargetModule, valModule));
+}
+
+/** Is this a view pointer that carries the module it names? */
+function isViewHandle(value) {
+  return _typeof(value) === "object" && value !== null && ViewTargetModule in value && value[ViewTargetModule] !== undefined;
+}
+
+/** The module a handle carries, or undefined if it carries none. */
+function viewHandleModule(value) {
+  if (!isViewHandle(value)) {
+    return undefined;
+  }
+  return value[ViewTargetModule];
+}
+
+/**
+ * What a reader that needs a MODULE accepts, rather than a value.
+ *
+ * `useValKey`, `useValRoute`, `useValRouteUrl` and their `fetch*` counterparts
+ * all read a path, a schema and a source off what they are handed, so — unlike
+ * `useVal` — they cannot take an arbitrary selector. They CAN take a view
+ * pointing at one, which is the point of a page declaring which module it
+ * shows. {@link resolveViewedModule} is the runtime half, and takes exactly
+ * this, so the two cannot drift.
+ */
+
+/**
+ * What a reader was actually handed: the module itself, or — when it is a view
+ * handle — the module that view points at.
+ *
+ * Every reader that needs a module rather than a value goes through this:
+ * `useValKey`, `useValRoute`, `useValRouteUrl` and their `fetch*` counterparts
+ * all pull the path, the schema and the source off the thing they are given,
+ * and a view handle has none of those. It is `{ view: "/foo.val.ts" }` with the
+ * module on a symbol, so reading `Internal.getValPath` off it gives
+ * `undefined`, and every one of those readers treats `undefined` as its own
+ * "no route matched" answer. Without this the call is not an error — it is a
+ * silently empty one.
+ *
+ * A POINTER with no module on it throws rather than being passed through, for
+ * the same reason `stegaEncode` throws on one: symbols do not survive
+ * serialization, so a handle that crossed the server/client boundary as a prop
+ * arrives looking like content and is not.
+ */
+
+/*
+ * A widened implementation signature rather than assertions in the body.
+ *
+ * The module rides on a symbol as `unknown` — the encoder that attaches it has
+ * no type for it — and no narrowing tells the checker that what is left after
+ * both guards is the module arm. Declaring the callable signature above and
+ * implementing against `unknown` says that once, where the runtime fact lives,
+ * instead of casting at each of the twelve readers.
+ */
+function resolveViewedModule(selector) {
+  var resolved = viewHandleModule(selector);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+  if (isValViewSource(selector)) {
+    throw Error("Cannot resolve the view of '".concat(selector.view, "': it carries no module. ") + "Either it crossed a server/client boundary, which drops the module because it rides on a symbol, " + "or it points at a different module than its schema declares \u2014 which `val validate --fix` repairs. " + "Resolve it in the same component that read the module containing it, or read '".concat(selector.view, "' directly."));
+  }
+  return selector;
+}
+
+/**
+ * Every module a schema's views point at, keyed by path.
+ *
+ * Walked GENERICALLY over the schema instance's own properties rather than by
+ * switching on schema type, for the same reason `viewTargetsOf` is: a schema
+ * holds another schema in places an enumeration keeps forgetting. Missing a
+ * site here is a view that cannot be resolved at runtime, which is a worse
+ * failure than the walk being slightly broad.
+ *
+ * Memoised per schema INSTANCE. A module's schema is built once at import, and
+ * `useVal` runs on every render — so without this the walk would be a render
+ * cost rather than a load cost.
+ */
+var cache = new WeakMap();
+function viewModulesOf(schema) {
+  if (schema === undefined) {
+    return new Map();
+  }
+  var cached = cache.get(schema);
+  if (cached) {
+    return cached;
+  }
+  var modules = new Map();
+  var seen = new Set();
+  function walk(node) {
+    if (_typeof(node) !== "object" || node === null || seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+    if (node instanceof ValViewSchema) {
+      var target = node["moduleFilePath"];
+      var valModule = node["valModule"];
+      if (typeof target === "string" && valModule !== undefined) {
+        modules.set(target, valModule);
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      var _iterator = result._createForOfIteratorHelper(node),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var item = _step.value;
+          walk(item);
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return;
+    }
+    for (var _i = 0, _Object$values = Object.values(node); _i < _Object$values.length; _i++) {
+      var value = _Object$values[_i];
+      walk(value);
+    }
+  }
+  walk(schema);
+  cache.set(schema, modules);
+  return modules;
+}
+
 function deserializeSchema(serialized) {
   var schema = deserializeSchemaImpl(serialized);
   if (serialized.readonly) {
@@ -12486,7 +13510,7 @@ function deserializeSchema(serialized) {
   return schema;
 }
 function deserializeSchemaImpl(serialized) {
-  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$render8, _serialized$accept, _serialized$dir, _serialized$remote, _serialized$jsonValue, _serialized$render0, _serialized$external, _serialized$render1, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15, _serialized$render16, _serialized$render17;
+  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$render8, _serialized$accept, _serialized$dir, _serialized$remote, _serialized$jsonValue, _serialized$render0, _serialized$external, _serialized$render1, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15, _serialized$render16, _serialized$render17, _serialized$readonly, _serialized$hidden, _serialized$render18;
   switch (serialized.type) {
     case "string":
       return new StringSchema(_objectSpread2(_objectSpread2({}, serialized.options), {}, {
@@ -12583,6 +13607,11 @@ function deserializeSchemaImpl(serialized) {
       return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render16 = serialized.render) !== null && _serialized$render16 !== void 0 ? _serialized$render16 : null);
     case "code":
       return new CodeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render17 = serialized.render) !== null && _serialized$render17 !== void 0 ? _serialized$render17 : null);
+    case "view":
+      return new ValViewSchema(serialized.moduleFilePath,
+      // No module: this schema came off the wire. The Studio navigates to a
+      // view rather than resolving one, so nothing here needs it.
+      undefined, (_serialized$readonly = serialized.readonly) !== null && _serialized$readonly !== void 0 ? _serialized$readonly : false, (_serialized$hidden = serialized.hidden) !== null && _serialized$hidden !== void 0 ? _serialized$hidden : false, serialized.description, (_serialized$render18 = serialized.render) !== null && _serialized$render18 !== void 0 ? _serialized$render18 : null);
     default:
       {
         var exhaustiveCheck = serialized;
@@ -12597,142 +13626,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:
+ * THE RULE, and the only sentence that needs to be remembered:
  *
- * ```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.
+ *   **`.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.**
  *
- * 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.
- */
-
-/**
- * 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.
- */
-
-/**
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * None of the three substitutes for another: a field with a perfect
+ * description still previews as `#3` until someone writes the preview.
  */
-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
@@ -13249,7 +14167,7 @@ function isPageRouter(routerId) {
 
 var corePackageJson = {
 	name: "@valbuild/core",
-	version: "0.129.0",
+	version: "0.134.0",
 	"private": false,
 	description: "Val - supercharged hard-coded content",
 	repository: {
@@ -13311,6 +14229,14 @@ var Internal = {
   VERSION: {
     core: corePackageJson.version
   },
+  // A view's read-path plumbing: `Internal` rather than the public surface,
+  // because an app never builds or unwraps a handle — it passes one to
+  // `useVal`.
+  createViewHandle: createViewHandle,
+  isViewHandle: isViewHandle,
+  resolveViewedModule: resolveViewedModule,
+  viewHandleModule: viewHandleModule,
+  viewModulesOf: viewModulesOf,
   mediaUrl: mediaUrl,
   resolveMedia: resolveMedia,
   isRemoteMediaPath: isRemoteMediaPath,
@@ -13458,6 +14384,7 @@ exports.THEME_LOGO_DIRECTORY = THEME_LOGO_DIRECTORY;
 exports.THEME_RADIUS_LENGTHS = THEME_RADIUS_LENGTHS;
 exports.THEME_RADIUS_STEPS = THEME_RADIUS_STEPS;
 exports.VAL_EXTENSION = VAL_EXTENSION;
+exports.ValViewSchema = ValViewSchema;
 exports._classCallCheck = _classCallCheck;
 exports._createClass = _createClass;
 exports._slicedToArray = _slicedToArray;
@@ -13477,6 +14404,7 @@ exports.initVal = initVal;
 exports.isInlineRender = isInlineRender;
 exports.isPageRouter = isPageRouter;
 exports.isRootModuleFilePath = isRootModuleFilePath;
+exports.isValViewSource = isValViewSource;
 exports.localeOfValue = localeOfValue;
 exports.localeTagError = localeTagError;
 exports.missingDeclaredKeys = missingDeclaredKeys;