@valbuild/core 0.130.0 → 0.134.0

package/CHANGELOG.md

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

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

@@ -65,6 +65,11 @@ export { type SerializedCodeSchema, type CodeOptions, type CodeLanguage, CodeSch
 export { type ColorFormat, type ParsedColor, COLOR_FORMATS, DEFAULT_COLOR_FORMAT, } from "./schema/colorFormat.js";
 export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetime.js";
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
+export { type SerializedValViewSchema, ValViewSchema } from "./schema/view.js";
+export { type ValViewSource, isValViewSource } from "./source/view.js";
+export type { ValView } from "./selector/view.js";
+export type { ValViewHandle, ResolvableModule } from "./source/viewHandle.js";
+import { createViewHandle, isViewHandle, resolveViewedModule, viewHandleModule, viewModulesOf } from "./source/viewHandle.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
 export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtext.js";
 export { type SerializedDiscriminatedUnionSchema, type DiscriminatedUnionSourceOf, DiscriminatedUnionSchema, } from "./schema/discriminatedUnion.js";
@@ -85,6 +90,11 @@ declare const Internal: {
     VERSION: {
         core: string;
     };
+    createViewHandle: typeof createViewHandle;
+    isViewHandle: typeof isViewHandle;
+    resolveViewedModule: typeof resolveViewedModule;
+    viewHandleModule: typeof viewHandleModule;
+    viewModulesOf: typeof viewModulesOf;
     mediaUrl: typeof mediaUrl;
     resolveMedia: typeof resolveMedia;
     isRemoteMediaPath: typeof isRemoteMediaPath;

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

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

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

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

package/dist/declarations/src/schema/index.d.ts

@@ -5,6 +5,7 @@ import { SerializedBooleanSchema } from "./boolean.js";
 import { SerializedFileSchema } from "./file.js";
 import { SerializedImageSchema } from "./image.js";
 import { SerializedKeyOfSchema } from "./keyOf.js";
+import { SerializedValViewSchema } from "./view.js";
 import { SerializedLiteralSchema } from "./literal.js";
 import { SerializedNumberSchema } from "./number.js";
 import { SerializedObjectSchema } from "./object.js";
@@ -24,7 +25,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
 import { ReifiedPreview, PreviewScope, PreviewItem } from "../preview.js";
-export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema | SerializedValViewSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;

package/dist/declarations/src/schema/object.d.ts

@@ -28,6 +28,16 @@ type ObjectSchemaProps = {
     _type?: never;
     /** Cannot create object with key: _ref. It is a reserved name */
     _ref?: never;
+    /**
+     * Cannot create object with key: view. It is a reserved name.
+     *
+     * A view field's source is `{ view: "/other.val.ts" }`, and the read side
+     * maps that shape to an opaque {@link ValView} handle. An ordinary object
+     * with a single `view: string` key is structurally identical, so it would be
+     * mapped the same way and lose every one of its fields — silently. Reserving
+     * the key is what makes the shape unambiguous.
+     */
+    view?: never;
     /** Cannot create object with key: andThen. It is a reserved name */
     andThen?: never;
     /** Cannot create object with key: assert. It is a reserved name */

package/dist/declarations/src/schema/validation/ValidationFix.d.ts

@@ -1,2 +1,2 @@
-export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "locale:check-locale", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "record:fill-keys", "external:upload"];
+export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "locale:check-locale", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "record:fill-keys", "external:upload", "view:check-module"];
 export type ValidationFix = (typeof ValidationFix)[number];

package/dist/declarations/src/schema/view.d.ts

@@ -0,0 +1,197 @@
+import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
+import type { ModuleIdOf, ValModuleBrand } from "../module.js";
+import { ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
+import { GenericSelector } from "../selector/index.js";
+import { Source } from "../source/index.js";
+import { ValViewSource } from "../source/view.js";
+import { ModuleFilePath, SourcePath } from "../val/index.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type SerializedValViewSchema = {
+    type: "view";
+    render?: FieldRender;
+    /** Never set: a view has no value of its own to preview. Carried for shape parity. */
+    preview?: true;
+    /** Always false: a view points at a module, and `null` is not a module. */
+    opt: false;
+    /** Always false: there is no value for a custom validator to look at. */
+    customValidate?: false;
+    /** The module this field points at. */
+    moduleFilePath: ModuleFilePath;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/** The source type of the module a selector points at. */
+type SourceOf<M> = M extends GenericSelector<infer S> ? S : never;
+/**
+ * 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.
+ */
+export declare class ValViewSchema<Id extends string = string, T = unknown> extends Schema<ValViewSource<Id, T>> {
+    private readonly moduleFilePath;
+    /**
+     * The module this points at, as an object.
+     *
+     * Not serialized and not part of the schema's identity — it is here so the
+     * READ path can resolve a view without a path-to-module registry, which the
+     * app does not have (`val.modules` is lazy thunks, `<ValModulesClient>` is
+     * optional). Absent on a schema that came off the wire, which is fine: the
+     * Studio navigates to a view, it does not resolve one.
+     */
+    private readonly valModule;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    constructor(moduleFilePath: Id, 
+    /**
+     * The module this points at, as an object.
+     *
+     * Not serialized and not part of the schema's identity — it is here so the
+     * READ path can resolve a view without a path-to-module registry, which the
+     * app does not have (`val.modules` is lazy thunks, `<ValModulesClient>` is
+     * optional). Absent on a schema that came off the wire, which is fine: the
+     * Studio navigates to a view, it does not resolve one.
+     */
+    valModule?: unknown, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null);
+    /**
+     * 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",
+     * });
+     */
+    describe(description: string | null): ValViewSchema<Id, T>;
+    /**
+     * 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.
+     */
+    protected executeValidate(path: SourcePath, src: ValViewSource<Id, T>): ValidationErrors;
+    protected executeCustomValidateAt(_path: SourcePath, _src: ValViewSource<Id, T>): ValidationError[];
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<ValViewSource<Id, T>>;
+    /**
+     * 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",
+     * });
+     */
+    nullable(): Schema<ValViewSource<Id, T> | null>;
+    /**
+     * 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",
+     * });
+     */
+    readonly(isReadonly?: boolean): ValViewSchema<Id, T>;
+    /**
+     * 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",
+     * });
+     */
+    hidden(isHidden?: boolean): ValViewSchema<Id, T>;
+    /**
+     * 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",
+     * });
+     */
+    render(input: FieldRender): ValViewSchema<Id, T>;
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(): ReifiedPreview;
+}
+/**
+ * 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",
+ * });
+ */
+export declare const view: <M extends GenericSelector<Source> & ValModuleBrand>(valModule: M) => ValViewSchema<ModuleIdOf<M>, SourceOf<M>>;
+export {};

package/dist/declarations/src/selector/index.d.ts

@@ -13,11 +13,13 @@ import { AllRichTextOptions, RichTextSource } from "../source/richtext.js";
 import { RichTextSelector } from "./richtext.js";
 import { JsonSource } from "../source/json.js";
 import { ExternalRecordSrc } from "../source/external.js";
+import { ValViewSource } from "../source/view.js";
+import { ValView } from "./view.js";
 import { SettingsSource } from "../source/settings.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends ExternalRecordSrc ? GenericSelector<T> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends ExternalRecordSrc ? GenericSelector<T> : T extends ValViewSource<string, infer Target> ? ValView<Target> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | ExternalRecordSrc | ValViewSource | ValView<Source> | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

package/dist/declarations/src/selector/view.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Type-level-only slot naming the source type of the module a {@link ValView}
+ * points at. Required, not optional: nothing else should ever be a `ValView` by
+ * accident, and reading a property off one has to be an error.
+ */
+declare const ViewTarget: unique symbol;
+/**
+ * A pointer to another module, as consuming code sees it.
+ *
+ * It has no properties on purpose. A view exists for the Val editor — it puts a
+ * way into another module on this module's screen — and there is nothing in it
+ * to render. Read the module it names directly.
+ *
+ * `T` is the target's source type. It is what lets `useVal(page.header)` be
+ * typed as the header's content — the overload that resolves a handle
+ * constrains `T` to `Source` there rather than here, because `ValViewSource` is a
+ * member of the `Source` union and a constraint here is a circular reference.
+ */
+export type ValView<T> = {
+    readonly [ViewTarget]: T;
+};
+export {};

package/dist/declarations/src/source/index.d.ts

@@ -1,9 +1,10 @@
 import { ExternalRecordSrc } from "./external.js";
+import { ValViewSource } from "./view.js";
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
 import { SettingsSource } from "./settings.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | ValViewSource | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {

package/dist/declarations/src/source/view.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+declare const ViewTargetSource: unique symbol;
+/**
+ * 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.
+ */
+export type ValViewSource<Id extends string = string, T = unknown> = {
+    readonly view: Id;
+} & {
+    readonly [ViewTargetSource]?: T;
+};
+/**
+ * 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.
+ */
+export declare function isValViewSource(value: unknown): value is ValViewSource;
+export {};

package/dist/declarations/src/source/viewHandle.d.ts

@@ -0,0 +1,69 @@
+import type { ValModule } from "../module.js";
+import { Schema } from "../schema/index.js";
+import type { GenericSelector, SelectorSource } from "../selector/index.js";
+import type { ValView } from "../selector/view.js";
+import type { Source, SourceObject } from "./index.js";
+import { ValViewSource } from "./view.js";
+/**
+ * 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.
+ */
+declare const ViewTargetModule: unique symbol;
+/**
+ * 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.
+ */
+export type ValViewHandle = ValViewSource & {
+    readonly [ViewTargetModule]: unknown;
+};
+/** Attach the module a view names to its pointer. */
+export declare function createViewHandle(source: ValViewSource, valModule: unknown): ValViewHandle;
+/** Is this a view pointer that carries the module it names? */
+export declare function isViewHandle(value: unknown): value is ValViewHandle;
+/** The module a handle carries, or undefined if it carries none. */
+export declare function viewHandleModule(value: unknown): unknown;
+/**
+ * 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.
+ */
+export type ResolvableModule<S extends Source = SourceObject> = ValModule<GenericSelector<S>> | ValView<S>;
+/**
+ * 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.
+ */
+export declare function resolveViewedModule<S extends Source>(selector: ResolvableModule<S>): ValModule<GenericSelector<S>>;
+export declare function viewModulesOf(schema: Schema<SelectorSource> | undefined): Map<string, unknown>;
+export {};