@valbuild/core 0.130.0 → 0.134.0

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

@@ -8791,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.
  *
@@ -8810,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) {
@@ -11499,6 +11821,7 @@ function initSchema() {
     image: image,
     literal: literal,
     keyOf: keyOf,
+    view: view,
     record: record,
     file: file,
     fileset: fileset,
@@ -12006,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
@@ -12173,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:
@@ -12326,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,
@@ -12433,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;
@@ -12508,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
@@ -12824,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) {
@@ -12835,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), {}, {
@@ -12932,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;
@@ -13487,7 +14165,7 @@ function isPageRouter(routerId) {
 
 var corePackageJson = {
 	name: "@valbuild/core",
-	version: "0.130.0",
+	version: "0.134.0",
 	"private": false,
 	description: "Val - supercharged hard-coded content",
 	repository: {
@@ -13549,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,
@@ -13658,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 };