@valbuild/core 0.101.0 → 0.103.0

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

@@ -21,7 +21,7 @@ export type ExtractedValModules = {
  * Extracts schemas and sources from a ValModules registry and computes the
  * deterministic SHAs that the server and client both use to detect changes.
  *
- * Used by ValOps on the server and by ValSyncEngine on the client so the
+ * Used by ValOps on the server and by `HostStore` on the client so the
  * hash algorithm has a single source of truth.
  */
 export declare function extractValModules(valModules: ValModules): Promise<ExtractedValModules>;

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

@@ -3,22 +3,23 @@ export { modules, type ValModules } from "./modules.js";
 export { extractValModules, type ExtractedValModules, type ExtractedModuleError, } from "./extractValModules.js";
 export type { InitVal, ValConfig, ValConstructor, ContentConstructor, } from "./initVal.js";
 export { Schema, type SerializedSchema, type SelectorOfSchema } from "./schema/index.js";
+export { hasRemoteFileSchema } from "./schema/hasRemoteFileSchema.js";
 export type { ImageMetadata } from "./schema/image.js";
 export type { FileMetadata } from "./schema/file.js";
 export type { ValModule, SerializedModule, InferValModuleType } from "./module.js";
 export type { SourceObject, SourcePrimitive, Source } from "./source/index.js";
-export type { FileSource } from "./source/file.js";
+export type { FileSource } from "./source/media.js";
 export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
-export type { RemoteSource, RemoteRef } from "./source/remote.js";
+export type { RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
-export type { ImageSource } from "./source/image.js";
+export type { ImageSource } from "./source/media.js";
+export type { MediaHotspot, MediaSource, GalleryImageSource, GalleryFileSource, } from "./source/media.js";
 export type { AllRichTextOptions, Bold, Styles, HeadingNode, ImageNode, Italic, LineThrough, ListItemNode, LinkNode, OrderedListNode, ParagraphNode, BrNode, RichTextNode, RichTextOptions, SerializedRichTextOptions, RichTextSource, BlockNode, SpanNode, UnorderedListNode, } from "./source/richtext.js";
 export { type Val, type SerializedVal, type ModuleFilePath, type PatchId, type ModulePath, type SourcePath, type JsonOfSource, type ParentPatchId, } from "./val/index.js";
 export type { Json, JsonPrimitive, JsonArray, JsonObject } from "./Json.js";
 export type { ValidationError, ValidationErrors, } from "./schema/validation/ValidationError.js";
 export type { ValidationFix } from "./schema/validation/ValidationFix.js";
-export { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG } from "./source/file.js";
 export { VAL_EXTENSION, type SourceArray } from "./source/index.js";
 export { derefPatch } from "./patch/deref.js";
 export { type SelectorSource, type SelectorOf, GenericSelector, } from "./selector/index.js";
@@ -27,20 +28,18 @@ declare const ModuleFilePathSep = "?p=";
 export { ModuleFilePathSep };
 import { SelectorSource, getSchema } from "./selector/index.js";
 import { ModulePath, SourcePath, getValPath, isVal } from "./val/index.js";
-import { convertFileSource } from "./schema/file.js";
 import { createValPathOfItem } from "./selector/SelectorProxy.js";
 import { Operation } from "./patch/index.js";
 import { initSchema } from "./initSchema.js";
 import { getMimeType, mimeTypeToFileExt, filenameToMimeType } from "./mimeType/index.js";
 import { type ImageMetadata } from "./schema/image.js";
 import { type FileMetadata } from "./schema/file.js";
-import { isFile } from "./source/file.js";
 import { isJson, getJsonImport, resolveJsonValues } from "./source/json.js";
 import { createRemoteRef } from "./source/remote.js";
 import { getValidationBasis, getValidationHash } from "./remote/validationBasis.js";
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
 import { splitRemoteRef } from "./remote/splitRemoteRef.js";
-import { convertRemoteSource } from "./schema/remote.js";
+import { fillFromGallery, isRemoteMediaPath, mediaUrl, resolveMedia } from "./source/media.js";
 import { colorToHex, convertColor, detectColorFormat, formatColor, parseColor } from "./schema/colorFormat.js";
 export { type SerializedArraySchema, ArraySchema } from "./schema/array.js";
 export { type SerializedObjectSchema, ObjectSchema } from "./schema/object.js";
@@ -60,7 +59,7 @@ export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtex
 export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
-export { type ListRecordRender, type ListArrayRender, type ReifiedRender, type CodeLanguage, type CodeRender, } from "./render.js";
+export { type ListRecordRender, type ListArrayRender, type ReifiedRender, type RenderScope, type CodeLanguage, type CodeRender, renderScope, } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
 export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];
@@ -71,8 +70,12 @@ declare const Internal: {
     VERSION: {
         core: string | null;
     };
-    convertFileSource: typeof convertFileSource;
-    convertRemoteSource: typeof convertRemoteSource;
+    mediaUrl: typeof mediaUrl;
+    resolveMedia: typeof resolveMedia;
+    isRemoteMediaPath: typeof isRemoteMediaPath;
+    media: {
+        fillFromGallery: typeof fillFromGallery;
+    };
     getSchema: typeof getSchema;
     getValPath: typeof getValPath;
     getSource: typeof getSource;
@@ -99,7 +102,6 @@ declare const Internal: {
     };
     validate: (val: ValModule<SelectorSource>, path: SourcePath, src: unknown) => import("./schema/validation/ValidationError.js").ValidationErrors | undefined;
     isVal: typeof isVal;
-    isFile: typeof isFile;
     isJson: typeof isJson;
     getJsonImport: typeof getJsonImport;
     resolveJsonValues: typeof resolveJsonValues;

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

@@ -99,19 +99,28 @@ export type InitSchema = {
     /**
      * Define an image.
      *
-     * Use c.image to create an image source.
+     * An image is an object with a `path`. `width`, `height` and `mimeType` are
+     * read from the file — the VS Code extension fills them in as you type the
+     * path, and `npx val validate --fix` adds any that are missing. `alt` and
+     * `hotspot` are yours to set.
      *
      * @example
      * const schema = s.image();
-     * export default c.define("/example.val.ts", schema, c.image("/public/val/example.png", {
-     *  width: 100,
-     *  height: 100,
-     *  mimeType: "image/png",
-     *  hotspot: {
-     *    x: 0.5,
-     *    y: 0.5
-     *  }
-     * }));
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     *   alt: "An example",
+     *   hotspot: { x: 0.5, y: 0.5 },
+     * });
+     *
+     * @example
+     * // Backed by a gallery: width, height and mimeType live there.
+     * const schema = s.image(galleryVal);
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     * });
      *
      */
     readonly image: typeof image;
@@ -146,11 +155,15 @@ export type InitSchema = {
     /**
      * Define a file.
      *
-     * Use `c.file` to create a file source.
+     * A file is an object with a `path`. `mimeType` comes from the extension —
+     * `npx val validate --fix` adds it.
      *
      * @example
      * const schema = s.file();
-     * export default c.define("/example.val.ts", schema, c.file("/public/val/example.png"));
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
      *
      */
     readonly file: typeof file;
@@ -291,11 +304,11 @@ export declare function initSchema(): {
     }) => import("./schema/number.js").NumberSchema<number>;
     union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./schema/union.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
     richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./schema/richtext.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
-    image: (options?: import("./schema/image.js").ImageOptions | import("./module.js").ValModule<Record<string, import("./schema/images.js").ImagesEntryMetadata>>) => import("./schema/image.js").ImageSchema<import("./index.js").ImageSource | import("./index.js").RemoteSource<import("./schema/image.js").ImageMetadata | undefined>>;
+    image: typeof image;
     literal: <T extends string>(value: T) => import("./schema/literal.js").LiteralSchema<T>;
     keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./schema/keyOf.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("./schema/string.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./schema/string.js").RawString : never : never>;
     record: typeof record;
-    file: (options?: import("./schema/file.js").FileOptions | import("./module.js").ValModule<Record<string, import("./schema/files.js").FilesEntryMetadata>>) => import("./schema/file.js").FileSchema<import("./index.js").FileSource | import("./index.js").RemoteSource<import("./schema/file.js").FileMetadata | undefined>>;
+    file: typeof file;
     files: (options: import("./schema/files.js").FilesOptions) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
         mimeType: import("./schema/string.js").StringSchema<string>;
     }, {
@@ -306,7 +319,7 @@ export declare function initSchema(): {
     color: (options?: import("./schema/color.js").ColorOptions) => import("./schema/color.js").ColorSchema<import("./schema/string.js").RawString>;
     route: <T extends string>(options?: Record<string, never>) => import("./schema/route.js").RouteSchema<T>;
     router: typeof router;
-    images: <Accept extends `image/${string}`>(options?: import("./schema/images.js").ImagesOptions<Accept>) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
+    images: <Accept extends `image/${string}`>(options: import("./schema/images.js").ImagesOptions<Accept>) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
         width: import("./schema/number.js").NumberSchema<number>;
         height: import("./schema/number.js").NumberSchema<number>;
         mimeType: import("./schema/string.js").StringSchema<string>;

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

@@ -1,15 +1,9 @@
 import { define } from "./module.js";
 import { InitSchema } from "./initSchema.js";
 import { getValPath as getPath } from "./val/index.js";
-import { initFile } from "./source/file.js";
-import { initImage } from "./source/image.js";
 import { json } from "./source/json.js";
-import { initRemote } from "./source/remote.js";
 export type ContentConstructor = {
     define: typeof define;
-    file: ReturnType<typeof initFile>;
-    image: ReturnType<typeof initImage>;
-    remote: ReturnType<typeof initRemote>;
     json: typeof json;
 };
 export type ValConstructor = {

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

@@ -4,22 +4,19 @@ import { Source } from "./source/index.js";
 import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
-import { ImageSelector } from "./selector/image.js";
-import { ImageSource } from "./source/image.js";
 declare const brand: unique symbol;
 export type ValModule<T extends SelectorSource> = SelectorOf<T> & ValModuleBrand;
 export type ValModuleBrand = {
     [brand]: "ValModule";
 };
 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 ImageSelector ? ImageSource : T extends {
+export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSource extends T ? T : T extends RawString ? string : T extends {
     [key in string]: SelectorSource;
 } ? {
     [key in keyof T]: ReplaceRawStringWithString<T[key]>;
 } : T extends SelectorSource[] ? ReplaceRawStringWithString<T[number]>[] : T;
 export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
 schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
-export declare function enrichFileImageRemoteSourceWithMetadata<T extends SelectorSource>(source: T, schema: Schema<SelectorSource>): T;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
 export declare function splitModuleFilePathAndModulePath(path: SourcePath | ModuleFilePath): [moduleId: ModuleFilePath, path: ModulePath];
 export declare function joinModuleFilePathAndModulePath(moduleFilePath: ModuleFilePath, modulePath: ModulePath): SourcePath;

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

@@ -1,8 +1,6 @@
 import { Schema } from "./schema/index.js";
-import { ImageMetadata } from "./schema/image.js";
 import { SelectorSource } from "./selector/index.js";
-import { ImageSource } from "./source/image.js";
-import { RemoteSource } from "./source/remote.js";
+import { ImageSource } from "./source/media.js";
 import { ModuleFilePath, SourcePath } from "./val/index.js";
 export type ListRecordRender = {
     layout: "list";
@@ -12,18 +10,32 @@ export type ListRecordRender = {
         value: {
             title: string;
             subtitle?: string | null;
-            image?: ImageSource | RemoteSource<ImageMetadata> | null;
+            image?: ImageSource | null;
         }
     ][];
 };
 export type ListArrayRender = {
     layout: "list";
     parent: "array";
-    items: {
-        title: string;
-        subtitle?: string | null;
-        image?: ImageSource | RemoteSource<ImageMetadata> | null;
-    }[];
+    /**
+     * The rendered items, each PAIRED WITH ITS INDEX — the same
+     * `[key, value][]` shape {@link ListRecordRender} uses.
+     *
+     * Not a positionally-indexed array, and the reason is
+     * {@link RenderScope}: a render computed for a subset of paths carries only
+     * those items, so `items[i]` would silently read the wrong row. Carrying the
+     * index makes a windowed render impossible to misread — a consumer looks its
+     * index up rather than trusting a position — and makes the array and record
+     * shapes symmetric.
+     */
+    items: [
+        index: number,
+        value: {
+            title: string;
+            subtitle?: string | null;
+            image?: ImageSource | null;
+        }
+    ][];
 };
 export type TextareaRender = {
     layout: "textarea";
@@ -45,5 +57,42 @@ type WithStatus<T> = {
     data: T;
 };
 export type ReifiedRender = Record<SourcePath | ModuleFilePath, WithStatus<RenderTypes>>;
+/**
+ * Which paths a render is being computed FOR.
+ *
+ * `executeRender` takes a whole module, so one request has always walked every
+ * node in it and run every `select` closure — for `handboka`, with `select` 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 RenderScope.wants} — is a render AT this exact path wanted? A
+ *   container answers `true` here when the whole of it is being shown, and its
+ *   list render is then computed in full.
+ * - {@link RenderScope.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 renders a WINDOW: only
+ *   the items that were asked for. That is the case a single visible row is, and
+ *   it is why {@link ListArrayRender} carries indices.
+ *
+ * Absent scope means the whole module, which is what every existing caller
+ * passes and what every existing caller got.
+ */
+export type RenderScope = {
+    wants(path: SourcePath | ModuleFilePath): boolean;
+    wantsUnder(path: SourcePath | ModuleFilePath): boolean;
+};
+/**
+ * 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.
+ */
+export declare function renderScope(paths: readonly SourcePath[]): RenderScope;
 export type RenderSelector<T extends Schema<SelectorSource>> = T extends Schema<infer S> ? S : never;
 export {};

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

@@ -1,13 +1,23 @@
 import { Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { RenderSelector, ReifiedRender } from "../render.js";
+import { RenderSelector, ReifiedRender, RenderScope } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
-import { ImageSource } from "../source/image.js";
+import { ImageSource } from "../source/media.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedArraySchema = {
     type: "array";
     item: SerializedSchema;
     opt: boolean;
+    /**
+     * Set when this schema declares a `render`.
+     *
+     * The render itself cannot be serialized — `select` is a user closure — but
+     * whether one EXISTS can be, and that is worth carrying: it lets the non-host
+     * side skip asking the host to render a module that cannot produce one.
+     * Measured in a browser: mounting 260 fields across 141 modules spent ~2.3ms
+     * of 3.1ms calling `executeRender` on modules that returned nothing.
+     */
+    render?: true;
     customValidate?: boolean;
     readonly?: boolean;
     hidden?: boolean;
@@ -41,7 +51,7 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     hidden(): ArraySchema<T, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
+    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
     render(input: ArrayRenderInput<T>): ArraySchema<T, Src>;
 }
 export declare const array: <S extends Schema<SelectorSource>>(schema: S) => ArraySchema<S, SelectorOfSchema<S>[]>;

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

@@ -1,9 +1,9 @@
-import { Json } from "../Json.js";
-import { FileSource } from "../source/file.js";
+import { FileSource, GalleryFileSource } from "../source/media.js";
+export type { FileMetadata } from "../source/file.js";
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-import { RemoteSource, ValModule } from "../index.js";
+import { ValModule } from "../index.js";
 import { ReifiedRender } from "../render.js";
 import { FilesEntryMetadata } from "./files.js";
 export type FileOptions = {
@@ -20,10 +20,7 @@ export type SerializedFileSchema = {
     hidden?: boolean;
     description?: string;
 };
-export type FileMetadata = {
-    mimeType?: string;
-};
-export declare class FileSchema<Src extends FileSource<FileMetadata | undefined> | RemoteSource<FileMetadata | undefined> | null> extends Schema<Src> {
+export declare class FileSchema<Src extends FileSource | null> extends Schema<Src> {
     private readonly options?;
     private readonly opt;
     protected readonly isRemote: boolean;
@@ -34,9 +31,14 @@ export declare class FileSchema<Src extends FileSource<FileMetadata | undefined>
     private readonly description?;
     constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     describe(description: string | null): FileSchema<Src>;
-    remote(): FileSchema<Src | RemoteSource<FileMetadata | undefined>>;
+    remote(): FileSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): FileSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * The entries of the gallery this field points at, or null when it is a
+     * standalone field.
+     */
+    private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): FileSchema<Src | null>;
     readonly(): FileSchema<Src>;
@@ -45,12 +47,10 @@ export declare class FileSchema<Src extends FileSource<FileMetadata | undefined>
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }
-export declare const file: (options?: FileOptions | ValModule<Record<string, FilesEntryMetadata>>) => FileSchema<FileSource | RemoteSource<FileMetadata | undefined>>;
-export declare function convertFileSource<Metadata extends {
-    readonly [key: string]: Json;
-} | undefined = {
-    readonly [key: string]: Json;
-} | undefined>(src: FileSource<Metadata>): {
-    url: string;
-    metadata?: Metadata;
-};
+/**
+ * A file picked from a gallery. Its mime type lives in the gallery, so the
+ * field carries only the path.
+ */
+export declare function file(galleryModule: ValModule<Record<string, FilesEntryMetadata>>): FileSchema<GalleryFileSource>;
+/** A file of its own, carrying its own mime type. */
+export declare function file(options?: FileOptions): FileSchema<FileSource>;

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

@@ -14,9 +14,13 @@ export type FilesOptions = {
     /**
      * The directory where files should be stored.
      * Must start with "/public" (e.g., "/public/val/files")
-     * @default "/public/val"
+     *
+     * Required, and deliberately so: it decides where every uploaded file in this
+     * collection lands, and it used to default to "/public/val" — which meant a
+     * collection that had simply not said where it wanted its files silently shared
+     * a directory with every other one.
      */
-    directory?: "/public" | `/public/${string}`;
+    directory: "/public" | `/public/${string}`;
     /**
      * Whether remote files are allowed
      * @default false

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

@@ -0,0 +1,34 @@
+import type { SerializedSchema } from "./index.js";
+/**
+ * Does this schema store any file remotely?
+ *
+ * The one answer to that question. There used to be two — `hasRemoteFileSchema`
+ * in the server, gating whether `/save` demands remote credentials, and
+ * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
+ * and they disagreed about `s.images({ remote: true })`: the Studio's counted a
+ * remote media record, the server's did not, because a media collection
+ * serializes as a `record` of metadata rather than as an image schema.
+ *
+ * The server's answer was the wrong one, and silently so. With it false,
+ * `/save` runs `saveOrUploadFiles` in `skip-remote` mode, and that mode does not
+ * merely skip the upload — it drops every remote descriptor without an error. The
+ * commit then lands a remote ref with no bytes behind it: a broken image, in the
+ * repository, with nothing anywhere saying why.
+ *
+ * ## Why it stays a walk over the SERIALIZED schema
+ *
+ * Both callers have a `SerializedSchema` and not a `Schema`: the server reads
+ * them out of `getSchemas()`, and the Studio is handed them by `host.receive`.
+ * Asking the schema classes directly would mean a method on every one of them,
+ * and the two places that need the answer cannot call it.
+ *
+ * ## Throwing
+ *
+ * The `never` assignment at the end is the point of the default branch: adding a
+ * schema type without teaching this function about it must not compile. The throw
+ * is what happens if one arrives anyway — which for a caller reading schemas out
+ * of its own process should be impossible. A caller that cannot afford to throw
+ * (the Studio, whose whole UI is downstream of this) catches it; returning `false`
+ * instead would reintroduce exactly the silent skip described above.
+ */
+export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;

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

@@ -1,10 +1,8 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { FileSource } from "../source/file.js";
-import { ImageSource } from "../source/image.js";
+import { GalleryImageSource, ImageSource } from "../source/media.js";
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { RemoteSource } from "../source/remote.js";
 import { ReifiedRender } from "../render.js";
 import { ImagesEntryMetadata } from "./images.js";
 export type ImageOptions = {
@@ -34,7 +32,7 @@ export type ImageMetadata = {
         y: number;
     };
 };
-export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefined> | RemoteSource<ImageMetadata | undefined> | null> extends Schema<Src> {
+export declare class ImageSchema<Src extends ImageSource | null> extends Schema<Src> {
     private readonly options?;
     private readonly opt;
     protected readonly isRemote: boolean;
@@ -45,9 +43,14 @@ export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefine
     private readonly description?;
     constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     describe(description: string | null): ImageSchema<Src>;
-    remote(): ImageSchema<Src | RemoteSource<ImageMetadata | undefined>>;
+    remote(): ImageSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): ImageSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * The entries of the gallery this field points at, or null when it is a
+     * standalone field.
+     */
+    private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ImageSchema<Src | null>;
     readonly(): ImageSchema<Src>;
@@ -56,4 +59,10 @@ export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefine
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }
-export declare const image: (options?: ImageOptions | ValModule<Record<string, ImagesEntryMetadata>>) => ImageSchema<ImageSource | RemoteSource<ImageMetadata | undefined>>;
+/**
+ * An image picked from a gallery. Its dimensions and mime type live in the
+ * gallery, so the field carries only what a person typed.
+ */
+export declare function image(galleryModule: ValModule<Record<string, ImagesEntryMetadata>>): ImageSchema<GalleryImageSource>;
+/** An image of its own, carrying its own dimensions and mime type. */
+export declare function image(options?: ImageOptions): ImageSchema<ImageSource>;

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

@@ -20,9 +20,13 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
     /**
      * The directory where images should be stored.
      * Must start with "/public" (e.g., "/public/val/images")
-     * @default "/public/val"
+     *
+     * Required, and deliberately so: it decides where every uploaded file in this
+     * collection lands, and it used to default to "/public/val" — which meant a
+     * gallery that had simply not said where it wanted its files silently shared a
+     * directory with every other one.
      */
-    directory?: "/public" | `/public/${string}`;
+    directory: "/public" | `/public/${string}`;
     /**
      * Alt text schema. Can be:
      * - s.string() for required alt text
@@ -65,8 +69,9 @@ type ImagesItemSrc = {
 /**
  * Define a collection of images.
  *
- * All options are optional: `s.images()` accepts any image type (`"image/*"`) in
- * the default `/public/val` directory, with nullable alt text and remote disabled.
+ * `directory` is required — it decides where uploads land, so it is not something
+ * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
+ * text, remote disabled.
  *
  * @example
  * ```typescript
@@ -85,5 +90,5 @@ type ImagesItemSrc = {
  * });
  * ```
  */
-export declare const images: <Accept extends `image/${string}`>(options?: ImagesOptions<Accept>) => RecordSchema<ObjectSchema<ImagesItemProps, ImagesItemSrc>, Schema<string>, Record<string, ImagesEntryMetadata>>;
+export declare const images: <Accept extends `image/${string}`>(options: ImagesOptions<Accept>) => RecordSchema<ObjectSchema<ImagesItemProps, ImagesItemSrc>, Schema<string>, Record<string, ImagesEntryMetadata>>;
 export {};

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

@@ -17,9 +17,9 @@ import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
 import { SerializedRouteSchema } from "./route.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-import { FileSource } from "../source/file.js";
+import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedRender, RenderScope } from "../render.js";
 export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
@@ -106,7 +106,14 @@ export declare abstract class Schema<Src extends SelectorSource> {
      */
     abstract hidden(): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;
-    protected abstract executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
+    /**
+     * @param scope Which paths the caller needs a render for. Absent means the
+     * whole module, which is what every caller passed before scoping existed.
+     * See {@link RenderScope}: a container prunes recursion where nothing is
+     * wanted, and renders a WINDOW when its own path is not wanted but some of its
+     * items are — which is the single-visible-row case.
+     */
+    protected abstract executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
     /** MUTATES! since internal and perf sensitive */
     protected appendValidationError(current: ValidationErrors, path: SourcePath, message: string, value: unknown, schemaError?: boolean): ValidationErrors;
     /**

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedRender, RenderScope } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -52,7 +52,7 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     hidden(): ObjectSchema<Props, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
+    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
 }
 export declare const object: <Props extends ObjectSchemaProps>(schema: Props) => ObjectSchema<Props, ObjectSchemaSrcOf<Props>>;
 export {};