@valbuild/core 0.129.0 → 0.134.0

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

@@ -411,8 +411,93 @@ var Schema = /*#__PURE__*/function () {
      * For example, if you have an object schema, you must assert each key / value pair manually.
      */
   }, {
-    key: "executePreviewItem",
+    key: "executePreview",
     value:
+    /**
+     * This value's preview, and every preview below it.
+     *
+     * The default is the whole of it for a LEAF: a leaf has nothing below it, so
+     * all it can contribute is {@link PreviewNode.self}. Containers override this
+     * and recurse; object and discriminated union add nothing of their own beyond
+     * the self they inherit here, and array and record add `rows`.
+     *
+     * @param scope Which paths the caller needs a preview for. Absent means the
+     * whole module, which is what every caller passed before scoping existed.
+     * See {@link PreviewScope}: a container prunes recursion where nothing is
+     * wanted, and previews a WINDOW when its own path is not wanted but some of
+     * its items are — which is the single-visible-row case.
+     * @param selfIsReifiedByParent Set by an array or record on its DIRECT items,
+     * and by nothing else. Such an item's preview is the same closure the
+     * container is already running into {@link PreviewNode.rows}, so emitting a
+     * `self` for it as well would call the user's closure twice per row — which
+     * it did, and which the scoped-preview tests caught by counting. The flag
+     * does not travel further down: a grandchild is nobody's row.
+     */
+    function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
+      if (selfIsReifiedByParent) {
+        return {};
+      }
+      return this.executeSelfPreview(sourcePath, src, scope);
+    }
+
+    /**
+     * THIS value as a preview, at its own path — `{ self }` and nothing else.
+     *
+     * Every schema can produce one, which is the point: before this existed a
+     * value's preview was reified only by its CONTAINER, so a value with no
+     * container had none. A module root is exactly that, and `.preview(...)` on
+     * a module's own schema was therefore dead code — the studio showed the file
+     * name and nothing a developer wrote could change it. So is any field of an
+     * object, which reifies no rows.
+     *
+     * Gated on {@link PreviewScope.wants} rather than `wantsUnder`: a caller
+     * asking about a CONTAINER wants its rows, and computing a self for every
+     * descendant on the way past would run each item's closure twice.
+     */
+  }, {
+    key: "executeSelfPreview",
+    value: function executeSelfPreview(sourcePath, src, scope) {
+      if (src === null || src === undefined) {
+        return {};
+      }
+      if (!this.declaresItemPreview()) {
+        return {};
+      }
+      if (scope !== undefined && !scope.wants(sourcePath)) {
+        return {};
+      }
+      try {
+        // NB NB: the closure is user code.
+        var item = this.executePreviewItem(src);
+        if (item === null) {
+          return {};
+        }
+        var title = item.title,
+          subtitle = item.subtitle,
+          image = item.image;
+        // Assigned into an annotated local rather than returned as a literal: a
+        // computed key widens `status` to `string`.
+        var res = {};
+        res[sourcePath] = {
+          status: "success",
+          data: {
+            self: {
+              title: title,
+              subtitle: subtitle,
+              image: image
+            }
+          }
+        };
+        return res;
+      } catch (e) {
+        var _res = {};
+        _res[sourcePath] = {
+          status: "error",
+          message: e instanceof Error ? e.message : "Unknown error"
+        };
+        return _res;
+      }
+    }
     /**
      * This value AS A PREVIEW — what a container's row, a reference dropdown or
      * a search hit shows for it. Runs the schema's own `preview` closure;
@@ -423,7 +508,9 @@ var Schema = /*#__PURE__*/function () {
      * `executePreview` reifies an {@link ArrayPreview} / {@link RecordPreview}
      * from item-level declarations.
      */
-    function executePreviewItem(src) {
+  }, {
+    key: "executePreviewItem",
+    value: function executePreviewItem(src) {
       return null;
     }
     /**
@@ -504,6 +591,241 @@ var Schema = /*#__PURE__*/function () {
 
 // TODO: SourceError<"Could not determine type of Schema">
 
+function ownKeys(e, r) {
+  var t = Object.keys(e);
+  if (Object.getOwnPropertySymbols) {
+    var o = Object.getOwnPropertySymbols(e);
+    r && (o = o.filter(function (r) {
+      return Object.getOwnPropertyDescriptor(e, r).enumerable;
+    })), t.push.apply(t, o);
+  }
+  return t;
+}
+function _objectSpread2(e) {
+  for (var r = 1; r < arguments.length; r++) {
+    var t = null != arguments[r] ? arguments[r] : {};
+    r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
+      _defineProperty(e, r, t[r]);
+    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
+      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+    });
+  }
+  return e;
+}
+
+/**
+ * THE RULE, and the only sentence that needs to be remembered:
+ *
+ *   **`.describe()` is INPUT HELP and is shown wherever that field — or a
+ *   record's key — is being ENTERED; `.preview()` is a NAME and is shown
+ *   wherever the value is REFERRED TO rather than edited; `.render()` is
+ *   LAYOUT and applies only while the field is open in front of you.**
+ *
+ * The test that settles every case: **can the reader change something here?**
+ * If yes it is a place for a description — the input beside a label, the key
+ * box in "New entry", "Rename key", "Duplicate", "New page", the key half of a
+ * reference dropdown. If no, it is a place for a preview — a list row, a
+ * reference once chosen, a search hit, a sitemap row, the heading of what you
+ * navigated to.
+ *
+ * That is why a description is plain data on the serialized schema and a
+ * preview is a closure: a description is true before any value exists and says
+ * the same thing to everyone filling the field in, and a preview cannot exist
+ * without the one value it names. So a description must never be used as a
+ * subtitle — it would repeat one sentence under every row of a list — and a
+ * preview must never be used as help text, because there is nothing to preview
+ * until after the value has been entered.
+ *
+ * None of the three substitutes for another: a field with a perfect
+ * description still previews as `#3` until someone writes the preview.
+ */
+/**
+ * A PREVIEW is how a VALUE is shown wherever a preview of it is needed — a row
+ * in a sortable list, a key in a reference dropdown, a search hit, a
+ * reference — which is everywhere the value is NAVIGABLE to rather than open.
+ * It is never how the field itself is edited: that is a RENDER (`render.ts`),
+ * which applies only when you are looking at the field. The two do not
+ * intersect — a schema can carry both, and each is read in its own places.
+ *
+ * A preview is declared on the schema of the VALUE being previewed:
+ *
+ * ```ts
+ * const author = s.object({ name: s.string() })
+ *   .preview(({ val }) => ({ title: val.name }));
+ * const authors = s.array(author);
+ * ```
+ *
+ * The container reifies its rows by running each ITEM's preview closure — see
+ * {@link ArrayPreview} / {@link RecordPreview}. (Previews used to be declared
+ * on the container instead; a `.preview` on an array/record now previews the
+ * array/record itself as a value, for when IT is the item of something.)
+ */
+/**
+ * What a preview shows for one value: the user's `preview` callback returns
+ * this, and the Studio draws a row from it.
+ *
+ * NB: {@link ArrayPreview} / {@link RecordPreview} name the DATA a container
+ * previews with. The Studio also has React components called `ArrayPreview` /
+ * `RecordPreview` (the fallback rendering of an array / record field, part of
+ * the `<Type>Preview` convention in `components/Preview.tsx`). They do not
+ * collide today because no file needs both - if one ever does, alias this type
+ * at the import rather than renaming that convention.
+ */
+
+/**
+ * What `.preview(...)` takes, on every schema: the value's own source in, a
+ * {@link PreviewItem} out. `NonNullable` because a container skips null items
+ * rather than previewing them.
+ *
+ * Declared through method syntax deliberately (the same bivariance shape
+ * React's event handler types use): `nullable()` copies a schema's closure
+ * into the `Src | null` variant of the same class, and with a plain function
+ * type the checker cannot see that `NonNullable<Src | null>` IS
+ * `NonNullable<Src>` while `Src` is still a type parameter — every schema's
+ * `nullable()` would need a cast instead.
+ */
+
+/**
+ * How a CONTAINER's children preview. `parent` is the discriminant, and every
+ * consumer narrows on it rather than on the union as a whole. There is no
+ * `layout` here on purpose - how a preview is laid out is the editor's
+ * business, not the schema's.
+ */
+
+/**
+ * Everything known about ONE path, which is two independent things.
+ *
+ * They are separate fields rather than a union because a path can have both,
+ * and that is not a corner case: `s.array(section).preview(...)` where
+ * `section` also previews is a section list that shows its rows AND names
+ * itself when it is nested in something. One of them would have had to win.
+ *
+ * - {@link self} - what THIS value is called, from its own schema's
+ *   `.preview(...)`. This is the only answer for a value with no container to
+ *   ask: a module root (whose `.preview` was never run before this existed) and
+ *   any field of an object.
+ * - {@link rows} - what its CHILDREN are called, from the ITEM schema's
+ *   `.preview(...)`, reified by the container. Kept alongside `self` rather
+ *   than derived from the children's `self` entries because a list needs every
+ *   row in one answer, and because an EMPTY list still has to preview as an
+ *   empty list - which is a fact about the schema, not about any value.
+ */
+
+/**
+ * Fold `incoming` into `target`, path by path. MUTATES `target`.
+ *
+ * Every `executePreview` used to copy child results across with a plain
+ * assignment, which was fine while one path held one thing. It no longer does:
+ * a container writes `rows` at its own path and its `self` arrives from the
+ * same walk, so an overwrite silently drops whichever landed first. Merging is
+ * per FIELD, and an error at a path beats any data there - a preview that threw
+ * must not be reported as a preview that is merely absent.
+ */
+function mergePreviewInto(target, incoming) {
+  for (var keyS in incoming) {
+    var key = keyS;
+    var next = incoming[key];
+    var current = target[key];
+    if (current === undefined || next.status === "error") {
+      target[key] = next;
+      continue;
+    }
+    if (current.status === "error" || next.status === "loading") {
+      continue;
+    }
+    if (current.status === "loading") {
+      target[key] = next;
+      continue;
+    }
+    target[key] = {
+      status: "success",
+      data: _objectSpread2(_objectSpread2({}, current.data), next.data)
+    };
+  }
+}
+
+/**
+ * Which paths a preview is being computed FOR.
+ *
+ * `executePreview` takes a whole module, so one request has always walked every
+ * node in it and run every `preview` closure - for `handboka`, with `preview` at
+ * two nested array levels, that is every chapter and every section to serve one
+ * visible row. A scope is what makes the walk proportional to what is being
+ * looked at instead of to the project.
+ *
+ * Two questions, because a container and its items need different answers:
+ *
+ * - {@link PreviewScope.wants} - is a preview AT this exact path wanted? A
+ *   container answers `true` here when the whole of it is being shown, and its
+ *   preview is then computed in full.
+ * - {@link PreviewScope.wantsUnder} - could anything at or below this path be
+ *   wanted? Recursion is pruned where this is `false`, and a container whose own
+ *   path is not wanted but which has wanted descendants previews a WINDOW: only
+ *   the items that were asked for. That is the case a single visible row is, and
+ *   it is why {@link ArrayPreview} carries indices.
+ *
+ * Absent scope means the whole module, which is what every existing caller
+ * passes and what every existing caller got.
+ */
+
+/**
+ * A scope covering exactly `paths` and their subtrees.
+ *
+ * Compares SEGMENTS rather than string prefixes. A source path's module path is
+ * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
+ * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
+ * dot or a quote - `"title"` against `"titles"` being the cheapest example.
+ * Segments are parsed once here, not per comparison.
+ */
+function previewScope(paths) {
+  var wanted = paths.map(function (path) {
+    var _splitModuleFilePathA = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA2 = _slicedToArray(_splitModuleFilePathA, 2),
+      moduleFilePath = _splitModuleFilePathA2[0],
+      modulePath = _splitModuleFilePathA2[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  });
+  var parse = function parse(path) {
+    var _splitModuleFilePathA3 = splitModuleFilePathAndModulePath(path),
+      _splitModuleFilePathA4 = _slicedToArray(_splitModuleFilePathA3, 2),
+      moduleFilePath = _splitModuleFilePathA4[0],
+      modulePath = _splitModuleFilePathA4[1];
+    return {
+      moduleFilePath: moduleFilePath,
+      segments: modulePath === "" ? [] : splitModulePath(modulePath)
+    };
+  };
+  var isPrefix = function isPrefix(prefix, of) {
+    if (prefix.length > of.length) return false;
+    for (var i = 0; i < prefix.length; i++) {
+      if (prefix[i] !== of[i]) return false;
+    }
+    return true;
+  };
+  return {
+    wants: function wants(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && entry.segments.length === at.segments.length && isPrefix(entry.segments, at.segments);
+      });
+    },
+    wantsUnder: function wantsUnder(path) {
+      var at = parse(path);
+      return wanted.some(function (entry) {
+        return entry.moduleFilePath === at.moduleFilePath && (
+        // Either direction: a wanted path below `path` means recurse into it,
+        // and a wanted path ABOVE it means the whole subtree was asked for.
+        isPrefix(at.segments, entry.segments) || isPrefix(entry.segments, at.segments));
+      });
+    }
+  };
+}
+
+// TODO: improve this so that we do not get RawString and string, only string. Are there other things?
+
 // Identity symbols are registered in the global Symbol registry so that
 // multiple bundled copies of @valbuild/core (e.g. the editor SPA bundle vs.
 // the host Next.js bundle) resolve to the same Symbol instance. Without
@@ -616,28 +938,6 @@ function unsafeCreateSourcePath(path, itemKey) {
   return "".concat(path).concat(Internal.ModuleFilePathSep).concat(JSON.stringify(itemKey));
 }
 
-function ownKeys(e, r) {
-  var t = Object.keys(e);
-  if (Object.getOwnPropertySymbols) {
-    var o = Object.getOwnPropertySymbols(e);
-    r && (o = o.filter(function (r) {
-      return Object.getOwnPropertyDescriptor(e, r).enumerable;
-    })), t.push.apply(t, o);
-  }
-  return t;
-}
-function _objectSpread2(e) {
-  for (var r = 1; r < arguments.length; r++) {
-    var t = null != arguments[r] ? arguments[r] : {};
-    r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
-      _defineProperty(e, r, t[r]);
-    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
-      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
-    });
-  }
-  return e;
-}
-
 var StringSchema = /*#__PURE__*/function (_Schema) {
   function StringSchema(options) {
     var _this;
@@ -668,10 +968,13 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -1008,11 +1311,6 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      * is a `render`, which travels in the serialized schema instead of through
      * this pipeline.
      */
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var string = function string(options) {
@@ -1045,10 +1343,13 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -1360,7 +1661,7 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -1377,11 +1678,14 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.items[_key3]["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key4 = keyS;
-          res[_key4] = itemResult[_key4];
-        }
+        mergePreviewInto(res, this.items[_key3]["executePreview"](subPath, itemSrc, scope));
+      }
+      // An object reifies no rows of its own, so the only thing it adds is what
+      // IT is called — which nothing else can supply for a field of an object.
+      // Its own items are NOT rows, so the flag stops here rather than travelling
+      // down with the recursion above.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -1422,10 +1726,13 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -1584,7 +1891,7 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -1599,11 +1906,10 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.item["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key = keyS;
-          res[_key] = itemResult[_key];
-        }
+        mergePreviewInto(res,
+        // `true`: this item is a ROW, and its preview is the closure reified
+        // into `rows` below. See `executePreview` on `Schema`.
+        this.item["executePreview"](subPath, itemSrc, scope, true));
       }
       // The rows preview comes from the ITEM schema's own `preview` — the
       // container just runs it per row. Asked as a fact rather than by running
@@ -1650,13 +1956,29 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
             };
           }
         }
-        res[sourcePath] = {
+        var rows = {};
+        rows[sourcePath] = {
           status: "success",
           data: {
-            parent: "array",
-            items: items
+            rows: {
+              parent: "array",
+              items: items
+            }
           }
         };
+        mergePreviewInto(res, rows);
+      }
+      // ...and what the LIST ITSELF is called, which is a different closure on a
+      // different schema: `s.array(section.preview(...)).preview(...)` previews
+      // its rows AND names itself for when it is nested in something. Merged
+      // rather than assigned, or one of the two would win. See `PreviewNode`.
+      //
+      // Unless this list is itself a ROW of an outer array or record, which has
+      // already run this very closure to reify it — a container both PASSES the
+      // flag to its items and RECEIVES it as one, and honouring only the first
+      // half ran `s.array(s.array(x).preview(...))`'s closure twice per row.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -1759,10 +2081,13 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -1951,11 +2276,6 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var literal = function literal(value) {
@@ -2011,10 +2331,13 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so it is
-   * where you say what an editor needs to know but the field name cannot carry. It
-   * also travels in the serialized schema, which is what the AI assistant and the
-   * MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -2467,7 +2790,7 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -2492,10 +2815,16 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
         return false;
       });
       if (thisSchema) {
-        var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
-        for (var keyS in itemResult) {
-          var _key2 = keyS;
-          res[_key2] = itemResult[_key2];
+        // The variant owns the path — see the note on `executeCustomValidateAt`.
+        // It contributes a `self` of its own here; the union's comes second and
+        // wins, because `executePreviewItem` already encodes the precedence (the
+        // union's own closure if it has one, else the matched variant's) and
+        // there must not be a second copy of that rule.
+        // The variant SHARES this path, so the flag passes straight through: a
+        // union that is a row is a variant that is a row.
+        mergePreviewInto(res, thisSchema["executePreview"](sourcePath, src, scope, selfIsReifiedByParent));
+        if (!selfIsReifiedByParent) {
+          mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
         }
         return res;
       }
@@ -2508,8 +2837,8 @@ var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
   }]);
 }(Schema);
 var discriminatedUnion = function discriminatedUnion(key) {
-  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key3 = 1; _key3 < _len; _key3++) {
-    objects[_key3 - 1] = arguments[_key3];
+  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key2 = 1; _key2 < _len; _key2++) {
+    objects[_key2 - 1] = arguments[_key2];
   }
   return new DiscriminatedUnionSchema(key, objects);
 };
@@ -3486,10 +3815,13 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -3870,11 +4202,6 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -3930,10 +4257,13 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -4162,11 +4492,6 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var route = function route(options) {
@@ -4199,10 +4524,13 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -4848,11 +5176,6 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var richtext = function richtext(options) {
@@ -5367,10 +5690,13 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -6163,7 +6489,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -6188,11 +6514,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.item["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key3 = keyS;
-          res[_key3] = itemResult[_key3];
-        }
+        mergePreviewInto(res,
+        // `true`: this item is a ROW, and its preview is the closure reified
+        // into `rows` below. See `executePreview` on `Schema`.
+        this.item["executePreview"](subPath, itemSrc, scope, true));
       }
       // The entries preview comes from the ITEM schema's own `preview` — the
       // container just runs it per entry. Asked as a fact rather than by running
@@ -6204,7 +6529,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
         var items = [];
         for (var _i2 = 0, _Object$entries = Object.entries(src); _i2 < _Object$entries.length; _i2++) {
           var _Object$entries$_i = _slicedToArray(_Object$entries[_i2], 2),
-            _key4 = _Object$entries$_i[0],
+            _key3 = _Object$entries$_i[0],
             val = _Object$entries$_i[1];
           if (isJson(val)) {
             continue; // as above: nothing to select from an un-loaded entry
@@ -6212,7 +6537,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           if (val === null || val === undefined) {
             continue;
           }
-          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key4))) {
+          if (window !== null && !window.wantsUnder(unsafeCreateSourcePath(sourcePath, _key3))) {
             continue;
           }
           // Per KEY, not per record: the closure is user code, and one entry whose
@@ -6224,26 +6549,37 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
               var title = _item.title,
                 subtitle = _item.subtitle,
                 image = _item.image;
-              items.push([_key4, {
+              items.push([_key3, {
                 title: title,
                 subtitle: subtitle,
                 image: image
               }]);
             }
           } catch (e) {
-            res[unsafeCreateSourcePath(sourcePath, _key4)] = {
+            res[unsafeCreateSourcePath(sourcePath, _key3)] = {
               status: "error",
               message: e instanceof Error ? e.message : "Unknown error"
             };
           }
         }
-        res[sourcePath] = {
+        var rows = {};
+        rows[sourcePath] = {
           status: "success",
           data: {
-            parent: "record",
-            items: items
+            rows: {
+              parent: "record",
+              items: items
+            }
           }
         };
+        mergePreviewInto(res, rows);
+      }
+      // ...and what the RECORD ITSELF is called — a different closure on a
+      // different schema. Skipped when this record is itself a ROW, whose
+      // closure the outer container has already run. See the same block in
+      // `array`, and `PreviewNode`.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -6368,6 +6704,16 @@ function record(keyOrSchema, schema) {
  * written without removing the key.
  */
 
+/**
+ * How the Studio behaves for the people editing this project.
+ *
+ * Not how it looks — that is {@link ThemeSettingsSource} — and not one person's
+ * own preferences, which stay in their browser. This is the project's word on
+ * what its editors are offered, which is why it is content: a team that has
+ * decided something about the way they work should not need a developer and a
+ * deploy to say so.
+ */
+
 /**
  * How the Studio looks in this project.
  *
@@ -6735,11 +7081,6 @@ var LocaleSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -6784,10 +7125,13 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -6961,11 +7305,6 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var _boolean = function _boolean() {
@@ -7478,10 +7817,13 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -7705,11 +8047,6 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var color = function color(options) {
@@ -7760,10 +8097,13 @@ var EnumSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so it is
-   * where you say what an editor needs to know but the field name cannot carry. It
-   * also travels in the serialized schema, which is what the AI assistant and the
-   * MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -7976,12 +8316,6 @@ var EnumSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      // A leaf: nothing below it to preview.
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -8321,7 +8655,7 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
     }
   }, {
     key: "executePreview",
-    value: function executePreview(sourcePath, src, scope) {
+    value: function executePreview(sourcePath, src, scope, selfIsReifiedByParent) {
       var res = {};
       if (src === null) {
         return res;
@@ -8335,11 +8669,14 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.items[_key4]["executePreview"](subPath, itemSrc, scope);
-        for (var keyS in itemResult) {
-          var _key5 = keyS;
-          res[_key5] = itemResult[_key5];
-        }
+        mergePreviewInto(res, this.items[_key4]["executePreview"](subPath, itemSrc, scope));
+      }
+      // An object reifies no rows of its own, so the only thing it adds is what
+      // IT is called — which nothing else can supply for a field of an object.
+      // Its own items are NOT rows, so the flag stops here rather than travelling
+      // down with the recursion above.
+      if (!selfIsReifiedByParent) {
+        mergePreviewInto(res, this.executeSelfPreview(sourcePath, src, scope));
       }
       return res;
     }
@@ -8402,6 +8739,9 @@ function settings() {
         dir: THEME_LOGO_DIRECTORY
       }).nullable().describe("The project's own mark, shown where Val's is in the Studio. A square-ish mark rather than a wordmark: the slot is 32px wide.")
     }),
+    studio: new SettingsSchema({
+      tour: _boolean().nullable().describe("Whether editors are offered the guided tour of the Studio. Unset means yes. Off hides the offer for everyone on this project — the tour stays in Quick actions for anyone who wants it.")
+    }),
     locales: new SettingsSchema({
       // Nullable because the source type is, and because the Studio writes
       // `null` for every sibling the first time a section is created.
@@ -8451,6 +8791,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.
  *
@@ -8470,6 +9121,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) {
@@ -8579,10 +9241,25 @@ function resolvePath(path, valModule, schema) {
         if (_typeof(resolvedSource) !== "object" && !Array.isArray(resolvedSource)) {
           throw Error("Schema type error: expected source to be type of record, but got ".concat(_typeof(resolvedSource)));
         }
-        if (!resolvedSource[part]) {
+        // PRESENCE, not truthiness. An entry that exists and is falsy is an
+        // entry: `null` for a declared key nobody has written yet, but also `""`,
+        // `0` and `false` in any record at all. Testing the value made every one
+        // of those report as a key the record does not have, so nothing could
+        // resolve them — not the Studio, not the language server, not a fix.
+        //
+        // A record source that is itself `null` keeps resolving as `null`, one
+        // part per level, the way the object branch below does: the path still
+        // names a real place in the schema, and the caller wants the schema
+        // there in order to say that nothing is written yet.
+        //
+        // `hasOwnProperty`, never `in`: `in` walks the prototype chain, so
+        // `"toString"` would resolve on every record and hand back
+        // `Object.prototype.toString` as if it were Source. Same reason
+        // `patch/json.ts` guards every key it reads.
+        if (resolvedSource !== null && !Object.prototype.hasOwnProperty.call(resolvedSource, part)) {
           throw Error("Invalid path: record source did not have key ".concat(part, " from path: ").concat(path));
         }
-        resolvedSource = resolvedSource[part];
+        resolvedSource = resolvedSource === null ? resolvedSource : resolvedSource[part];
         resolvedSchema = resolvedSchema instanceof RecordSchema ? (_resolvedSchema2 = resolvedSchema) === null || _resolvedSchema2 === void 0 ? void 0 : _resolvedSchema2["item"] : resolvedSchema.item;
         // A `.jsonValues()` entry value is a lazily-loaded JsonSource marker. We
         // can resolve the entry itself (schema is now `item`), but we cannot
@@ -8784,7 +9461,15 @@ function safeResolvePath(path, valModule, schema) {
             }
           };
         }
-        if (resolvedSource[part] === undefined) {
+        // A `null` record keeps resolving as `null`, as the object branch below
+        // does — see the same note in `resolvePath`. Without it, indexing `null`
+        // threw a TypeError out of the function whose whole point is not to
+        // throw.
+        //
+        // Own properties only. Testing `resolvedSource[part] === undefined` let
+        // an inherited name through — `"toString"` is not undefined on any
+        // object — so the walk continued into `Object.prototype`.
+        if (resolvedSource !== null && !Object.prototype.hasOwnProperty.call(resolvedSource, part)) {
           return {
             v: {
               status: "source-undefined",
@@ -8794,7 +9479,7 @@ function safeResolvePath(path, valModule, schema) {
             }
           };
         }
-        resolvedSource = resolvedSource[part];
+        resolvedSource = resolvedSource === null ? resolvedSource : resolvedSource[part];
         resolvedSchema = resolvedSchema instanceof RecordSchema ? (_resolvedSchema4 = resolvedSchema) === null || _resolvedSchema4 === void 0 ? void 0 : _resolvedSchema4["item"] : resolvedSchema.item;
         // jsonValues entry: cannot descend deeper until the backing `*.val.json`
         // content is loaded into the source tree.
@@ -9053,10 +9738,13 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -9280,11 +9968,6 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var number = function number(options) {
@@ -9397,10 +10080,13 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -9682,11 +10368,6 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var keyOf = function keyOf(valModule) {
@@ -9743,10 +10424,13 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -10087,11 +10771,6 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 
@@ -10184,10 +10863,13 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -10432,11 +11114,6 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var date = function date(options) {
@@ -10469,10 +11146,13 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -10772,11 +11452,6 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var datetime = function datetime(options) {
@@ -10823,10 +11498,13 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
   /**
    * Describe this field.
    *
-   * The description is shown next to the field's label in the Val editor, so
-   * it is where you say what an editor needs to know but the field name cannot
-   * carry. It also travels in the serialized schema, which is what the AI
-   * assistant and the MCP tools read.
+   * The description is INPUT HELP: it is shown where this field's value is
+   * entered — beside its input in the Val editor, and for a record's key
+   * schema in every form that asks for a key — so it is where you say what an
+   * editor needs to know to fill it in RIGHT, which the field name cannot
+   * carry. It is not a name for the value: that is `.preview(...)`, and it is
+   * read somewhere else. The description also travels in the serialized
+   * schema, which is what the AI assistant and the MCP tools read.
    *
    * Pass `null` to clear a description set earlier.
    *
@@ -11017,11 +11695,6 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
         description: this.description
       };
     }
-  }, {
-    key: "executePreview",
-    value: function executePreview() {
-      return {};
-    }
   }]);
 }(Schema);
 var code = function code(options) {
@@ -11148,6 +11821,7 @@ function initSchema() {
     image: image,
     literal: literal,
     keyOf: keyOf,
+    view: view,
     record: record,
     file: file,
     fileset: fileset,
@@ -11655,6 +12329,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 = _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 = _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 = _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 = _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 = _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
@@ -11822,7 +12675,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:
@@ -11975,11 +12828,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 = _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,
@@ -12082,7 +12950,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;
@@ -12157,7 +13025,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
@@ -12473,6 +13343,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 = _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) {
@@ -12484,7 +13508,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), {}, {
@@ -12581,6 +13605,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;
@@ -12595,142 +13624,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
@@ -13247,7 +14165,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: {
@@ -13309,6 +14227,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,
@@ -13418,4 +14344,4 @@ function tryJsonParse(str) {
   }
 }
 
-export { KeyOfSchema as $, ArraySchema as A, BooleanSchema as B, localeTagError as C, DEFAULT_CONTENT_HOST as D, localeOfValue as E, FATAL_ERROR_TYPES as F, GenericSelector as G, declaredKeySetOf as H, Internal as I, missingDeclaredKeys as J, discriminatedUnionBranchOf as K, LocaleSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, ColorSchema as Q, RecordSchema as R, Schema as S, THEME_LOGO_DIRECTORY as T, CodeSchema as U, VAL_EXTENSION as V, CODE_LANGUAGES as W, COLOR_FORMATS as X, DEFAULT_COLOR_FORMAT as Y, DateTimeSchema as Z, _typeof as _, _slicedToArray as a, RouteSchema as a0, RichTextSchema as a1, DiscriminatedUnionSchema as a2, EnumSchema as a3, LiteralSchema as a4, deserializeSchema as a5, previewScope as a6, isInlineRender as a7, parseNextJsRoutePattern as a8, parseTanStackRoutePattern as a9, tanStackSegmentsOfRoutePath as aa, validateUrlAgainstPattern as ab, getSourcePathFromRoute as ac, isPageRouter as ad, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, THEME_RADIUS_STEPS as u, THEME_RADIUS_LENGTHS as v, assistantAvailability as w, SETTINGS_MODULE_CONVENTION as x, isRootModuleFilePath as y, resolveSettingsModule as z };
+export { KeyOfSchema as $, ArraySchema as A, BooleanSchema as B, localeTagError as C, DEFAULT_CONTENT_HOST as D, localeOfValue as E, FATAL_ERROR_TYPES as F, GenericSelector as G, declaredKeySetOf as H, Internal as I, missingDeclaredKeys as J, discriminatedUnionBranchOf as K, LocaleSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, ColorSchema as Q, RecordSchema as R, Schema as S, THEME_LOGO_DIRECTORY as T, CodeSchema as U, VAL_EXTENSION as V, CODE_LANGUAGES as W, COLOR_FORMATS as X, DEFAULT_COLOR_FORMAT as Y, DateTimeSchema as Z, _typeof as _, _slicedToArray as a, ValViewSchema as a0, isValViewSource as a1, RouteSchema as a2, RichTextSchema as a3, DiscriminatedUnionSchema as a4, EnumSchema as a5, LiteralSchema as a6, deserializeSchema as a7, previewScope as a8, isInlineRender as a9, parseNextJsRoutePattern as aa, parseTanStackRoutePattern as ab, tanStackSegmentsOfRoutePath as ac, validateUrlAgainstPattern as ad, getSourcePathFromRoute as ae, isPageRouter as af, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, THEME_RADIUS_STEPS as u, THEME_RADIUS_LENGTHS as v, assistantAvailability as w, SETTINGS_MODULE_CONVENTION as x, isRootModuleFilePath as y, resolveSettingsModule as z };