@valbuild/core 0.121.0 → 0.125.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @valbuild/core
 
+## 0.125.0
+
+### Minor Changes
+
+- [#638](https://github.com/valbuild/val/pull/638) [`c390397`](https://github.com/valbuild/val/commit/c390397cb5e203eb1bedae3a6fab15726e850b90) Thanks [@freekh](https://github.com/freekh)! - Val now runs on TanStack Start.
+
+  `@valbuild/tanstack` is a new package with everything `@valbuild/next` has: Val
+  Studio at `/val`, the on-page overlay and canvas, draft mode, the client hooks,
+  server-side content reads, images, and the MCP tools.
+
+  ```sh
+  npm install @valbuild/tanstack
+  ```
+
+  ```ts
+  // val.config.ts
+  import { initVal } from "@valbuild/tanstack";
+  const { s, c, config, tanstackRouter } = initVal({ project: "org/project" });
+  ```
+
+  **Routes are first class.** A Val module for a route is named after the route
+  file it sits beside — `src/routes/posts.$postId.tsx` is served content by
+  `src/routes/posts.$postId.val.ts` — and its keys are the URLs that route serves:
+
+  ```ts
+  export default c.define(
+    "/src/routes/posts.$postId.val.ts",
+    s.router(tanstackRouter, s.object({ title: s.string() })),
+    { "/posts/hello-world": { title: "Hello world" } },
+  );
+  ```
+
+  `.` and `/` both separate segments, `$param` is a parameter, `$` is a splat, and
+  `index`, `route`, `(groups)` and `_pathless` layouts add no URL segment — the
+  same rules TanStack Router uses for the route file itself. Val validates every
+  key against that pattern, and Val Studio shows these modules as a sitemap under
+  **Pages**, where an editor can add a page.
+
+  Point the route generator away from your content files, in `vite.config.ts` and
+  `tsr.config.json`:
+
+  ```ts
+  tanstackStart({ router: { routeFileIgnorePattern: "\\.val\\.[tj]sx?$" } });
+  ```
+
+  See the [README](https://github.com/valbuild/val/blob/main/packages/tanstack/README.md)
+  for the full wiring, and `examples/tanstack` for a working app.
+
+  **Also fixed, for everyone:** `Internal.VERSION.core` was `null` in any ESM
+  bundle — it was read with `require("../package.json")` inside a `try`, so the
+  failure was silent. That version goes into every remote file ref and proxy mode
+  refuses to start without it. Every package now reads its version through a
+  static JSON import, which is inlined at build time.
+
+  Two smaller fixes that came out of running the whole toolchain against a
+  TanStack project:
+
+  - `val versions` reports `@valbuild/tanstack`, and `val debug` writes a snapshot
+    that names whichever framework package the captured project actually has.
+  - `@valbuild/eslint-plugin` reads a `tsconfig.json` that has comments in it. A
+    tsconfig is JSONC, and `JSON.parse` is not — so on any project whose tsconfig
+    carries a comment (the TanStack starter's does) the
+    `module-in-val-modules` rule threw `Expected double-quoted property name in
+JSON` on the first file and took the whole lint run with it.
+
+  Three fixes found by driving the Studio against a real TanStack app:
+
+  - **A draft image now loads on the page.** The source the Studio pushes to the
+    host page carries `patch_id` for any file whose bytes are still in a patch, so
+    the page asks `/api/val/files/...?patch_id=` rather than a `/public` path that
+    nothing has written yet. This was silent — the image just did not appear — and
+    it affects any page that reads media through the hooks rather than on the
+    server, `@valbuild/next` included.
+  - **A splat route no longer logs an error on every render.** TanStack returns
+    both `_splat` and `*` for the same parameter; Val reported the second as a
+    parameter it could not place in the path.
+  - The TanStack example and starter render a 404 page instead of throwing
+    `notFound()` from a component, which escaped to the error boundary and logged
+    `Error in renderToReadableStream` (and, with no not-found component
+    configured, aborted the response) on every miss.
+
+## 0.124.0
+
+### Minor Changes
+
+- [#622](https://github.com/valbuild/val/pull/622) [`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.images()` and `s.files()` no longer take a `remote` option. Use
+  `.remote()`, the same way `s.image()` and `s.file()` already did.
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images", remote: true });
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+    remote: true,
+  });
+
+  // after
+  s.images({ directory: "/public/val/images" }).remote();
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+  }).remote();
+  ```
+
+  Behaviour is unchanged — remote is still off unless asked for. This only makes
+  remote one thing spelled one way across all four media schemas, instead of an
+  option on the two collections and a method on the two fields. `remote: false`
+  has no replacement because it was the default; drop it.
+
 ## 0.121.0
 
 ### Minor Changes

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

@@ -2,14 +2,23 @@ import type { ModuleFilePath, SourcePath } from "./val/index.js";
 import type { SerializedSchema } from "./schema/index.js";
 /**
  * Given a URL pathname (e.g. "/blogs/blog-1") and all serialized module schemas,
- * finds the matching next-app-router module and returns the module file path
- * and the source path for that route's content.
+ * finds the page-router module that serves that route and returns the module
+ * file path and the source path for that route's content.
  *
  * External routers (e.g. external-url-router) are intentionally skipped.
- * Returns null if no next-app-router module matches the pathname.
+ * Returns null if no page-router module matches the pathname.
  */
 export declare function getSourcePathFromRoute(pathname: string, schemas: Record<ModuleFilePath, SerializedSchema>): {
     moduleFilePath: ModuleFilePath;
     sourcePath: SourcePath;
     route: string;
 } | null;
+/**
+ * Whether a router id is one whose keys are routes of this site.
+ *
+ * The same question `getSourcePathFromRoute` asks, exported because the Studio
+ * asks it too — a page router gets the sitemap and the "Pages" menu, an
+ * external one gets a flat list of URLs — and the two must not disagree about
+ * which is which.
+ */
+export declare function isPageRouter(routerId: string): boolean;

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

@@ -3,13 +3,14 @@ export { modules, type ValModules } from "./modules.js";
 export { extractValModules, computeValModuleShas, type ExtractedValModules, type ValModuleShaEntry, type ValModuleShas, 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 { hasRemoteFileSchema, hasMediaSchema, } from "./schema/hasRemoteFileSchema.js";
 export type { ImageMetadata, ImageEncodeOption, ImageEncodeOptions, } 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/media.js";
 export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
+export type { ExternalRecordSrc, ExternalRecordWritableSrc, ExternalItemOf, ExternalLabelOf, ExternalReadonlyOf, } from "./source/external.js";
 export type { RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
@@ -35,6 +36,8 @@ import { getMimeType, mimeTypeToFileExt, filenameToMimeType, mimeTypeMatchesAcce
 import { type ImageMetadata } from "./schema/image.js";
 import { type FileMetadata } from "./schema/file.js";
 import { isJson, getJsonImport, resolveJsonValues } from "./source/json.js";
+import { isExternal, hasInlineExternalEntries } from "./source/external.js";
+import { createExternalFileRef, splitExternalFileRef, isExternalFileRef } from "./source/externalRef.js";
 import { createRemoteRef } from "./source/remote.js";
 import { getValidationBasis, getValidationHash } from "./remote/validationBasis.js";
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
@@ -66,14 +69,15 @@ export { deserializeSchema } from "./schema/deserialize.js";
 export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
 export { type InlineRender, type FieldRender, isInlineRender } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
-export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
+export { parseNextJsRoutePattern, parseTanStackRoutePattern, tanStackSegmentsOfRoutePath, validateUrlAgainstPattern, } from "./router.js";
+export { getSourcePathFromRoute, isPageRouter } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];
 export type FatalErrorType = (typeof FATAL_ERROR_TYPES)[number];
 export declare const DEFAULT_CONTENT_HOST = "https://content.val.build";
 export declare const DEFAULT_APP_HOST = "https://admin.val.build";
 declare const Internal: {
     VERSION: {
-        core: string | null;
+        core: string;
     };
     mediaUrl: typeof mediaUrl;
     resolveMedia: typeof resolveMedia;
@@ -90,6 +94,7 @@ declare const Internal: {
     splitModuleFilePathAndModulePath: typeof splitModuleFilePathAndModulePath;
     joinModuleFilePathAndModulePath: typeof joinModuleFilePathAndModulePath;
     nextAppRouter: import("./router.js").ValRouter;
+    tanstackRouter: import("./router.js").ValRouter;
     externalPageRouter: import("./router.js").ValRouter;
     color: {
         parseColor: typeof parseColor;
@@ -111,6 +116,11 @@ declare const Internal: {
     isJson: typeof isJson;
     getJsonImport: typeof getJsonImport;
     resolveJsonValues: typeof resolveJsonValues;
+    isExternal: typeof isExternal;
+    hasInlineExternalEntries: typeof hasInlineExternalEntries;
+    createExternalFileRef: typeof createExternalFileRef;
+    splitExternalFileRef: typeof splitExternalFileRef;
+    isExternalFileRef: typeof isExternalFileRef;
     createValPathOfItem: typeof createValPathOfItem;
     getSHA256Hash: (bits: Uint8Array) => string;
     initSchema: typeof initSchema;

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

@@ -2,9 +2,11 @@ import { define } from "./module.js";
 import { InitSchema } from "./initSchema.js";
 import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
+import { external } from "./source/external.js";
 export type ContentConstructor = {
     define: typeof define;
     json: typeof json;
+    external: typeof external;
 };
 export type ValConstructor = {
     unstable_getPath: typeof getPath;

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

@@ -1,6 +1,7 @@
 import { Schema, SelectorOfSchema, SerializedSchema } from "./schema/index.js";
 import { GenericSelector, SelectorOf, SelectorSource } from "./selector/index.js";
 import { Source } from "./source/index.js";
+import { ExternalRecordSrc } from "./source/external.js";
 import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
@@ -15,8 +16,24 @@ export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSourc
 } ? {
     [key in keyof T]: ReplaceRawStringWithString<T[key]>;
 } : T extends SelectorSource[] ? ReplaceRawStringWithString<T[number]>[] : T;
+/**
+ * What may be WRITTEN as an external record's source, on top of the marker.
+ *
+ * Entries inline in the `.val.ts` are accepted on purpose — the same call
+ * `.jsonValues()` makes for the same reason: pasting content straight into the
+ * module is the natural first thing to write, and a type error there is a dead
+ * end, because the author cannot see what to write instead. Validation reports
+ * them as an `external:upload` fix, and they are readable at runtime meanwhile.
+ *
+ * Widened HERE rather than in the schema's own source type so that the MODULE
+ * stays typed on the marker alone. An adapter is bound to a module, and a module
+ * whose type were "marker or plain record" would be indistinguishable from an
+ * ordinary record — which would let `entry()` accept a module that is not
+ * 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>>): ValModule<SelectorOfSchema<T>>;
+schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>> | InlineEntriesFor<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
 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/router.d.ts

@@ -23,6 +23,51 @@ export declare const nextAppRouter: ValRouter;
  * - /app/(..)(dashboard)/feed/page.val.ts -> ["feed"] (interception route)
  */
 export declare function parseNextJsRoutePattern(moduleFilePath: string): string[];
+/**
+ * Parse a TanStack Router route pattern out of a Val module file path.
+ *
+ * TanStack Router's file conventions are not Next's, so this is a different
+ * parser rather than a flag on the one above. A Val module for a route lives
+ * beside the route file and is named the same way — `routes/posts.$postId.tsx`
+ * is served content by `routes/posts.$postId.val.ts` — so the pattern is the
+ * file path with the conventions applied:
+ *
+ * - `.` and `/` both separate segments (`posts.$postId.val.ts` and
+ *   `posts/$postId.val.ts` are the same route)
+ * - `$param` is a dynamic segment, `$` on its own is a splat
+ * - `index` is the directory's own route and contributes no segment
+ * - `route` is a layout for the directory, likewise
+ * - `(group)` folders and `_pathless` layout segments are not in the URL
+ * - a trailing `_` on a segment opts out of nesting and is not in the URL
+ *
+ * The result is expressed in the SAME vocabulary the Next parser uses
+ * (`[param]`, `[...param]`), because everything downstream — validation, the
+ * sitemap, the key inputs in the Studio — is written against that vocabulary
+ * and there is no reason for two.
+ *
+ * - /src/routes/posts.$postId.val.ts -> ["posts", "[postId]"]
+ * - /routes/posts/$postId.val.ts     -> ["posts", "[postId]"]
+ * - /src/routes/index.val.ts         -> []
+ * - /src/routes/files.$.val.ts       -> ["files", "[..._splat]"]
+ * - /src/routes/(app)/_layout.about.val.ts -> ["about"]
+ */
+export declare function parseTanStackRoutePattern(moduleFilePath: string): string[];
+/**
+ * The URL segments of a TanStack route path, given relative to `routes/`.
+ *
+ * Exported because the Studio derives the same pattern from the same file path
+ * and must not disagree with validation about what a route is.
+ */
+export declare function tanStackSegmentsOfRoutePath(routePath: string): string[];
+/**
+ * The router for a TanStack Router (and TanStack Start) app.
+ *
+ * Like `nextAppRouter` this does not belong in core — it is here for the same
+ * reason that one is: the serialized schema carries only a router id, so the
+ * thing that turns an id back into a validator has to be somewhere every
+ * consumer can reach.
+ */
+export declare const tanstackRouter: ValRouter;
 export interface ValRouter {
     getRouterId(): string;
     validate(moduleFilePath: ModuleFilePath, urlPaths: string[]): RouteValidationError[];

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

@@ -21,11 +21,6 @@ export type FilesOptions = {
      * a directory with every other one.
      */
     directory: "/public" | `/public/${string}`;
-    /**
-     * Whether remote files are allowed
-     * @default false
-     */
-    remote?: boolean;
 };
 /**
  * Metadata for a file entry in the files record
@@ -43,6 +38,8 @@ type FilesItemSrc = {
 /**
  * Define a collection of files.
  *
+ * Remote is off by default: call `.remote()` on the result to allow remote files.
+ *
  * @example
  * ```typescript
  * const schema = s.files({

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

@@ -5,9 +5,10 @@ import type { SerializedSchema } from "./index.js";
  * 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.
+ * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * 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
@@ -32,3 +33,20 @@ import type { SerializedSchema } from "./index.js";
  * instead would reintroduce exactly the silent skip described above.
  */
 export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;
+/**
+ * Does this schema hold any media at all — remote or not?
+ *
+ * The sibling of {@link hasRemoteFileSchema}, and the same walk minus the
+ * `remote` predicate. It answers the question an external record has to ask
+ * before it will accept a binding: an item schema containing media needs a
+ * `putFile`/`getFile` pair, and without one that is a schema error.
+ *
+ * It is a walk over the SERIALIZED schema for the reasons given above, and for
+ * one more that is specific to this question: the two cases most likely to be
+ * missed are invisible to a value type. A media collection (`s.images()` /
+ * `s.files()`) serializes as a record of metadata with no image schema inside
+ * it, and a richtext inline image lives in a constructor argument. A check
+ * written against the item TYPE would silently pass both — and the gallery case
+ * already has a data-loss incident attached to it (see above).
+ */
+export declare function hasMediaSchema(schema: SerializedSchema): boolean;

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

@@ -35,11 +35,6 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * - s.record(s.string(), s.string()) for locale-based alt text
      */
     alt?: AltSchema;
-    /**
-     * Whether remote images are allowed
-     * @default false
-     */
-    remote?: boolean;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
@@ -79,7 +74,7 @@ type ImagesItemSrc = {
  *
  * `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.
+ * text, remote disabled. Call `.remote()` on the result to allow remote images.
  *
  * @example
  * ```typescript

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

@@ -4,6 +4,7 @@ import { FieldRender } from "../render.js";
 import { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
 import { JsonOf, JsonSource } from "../source/json.js";
+import { ExternalRecordSrc } from "../source/external.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import type { ImageEncodeOption } from "./image.js";
@@ -38,6 +39,12 @@ export type SerializedRecordSchema = {
     encode?: ImageEncodeOption;
     alt?: SerializedSchema;
     jsonValues?: boolean;
+    /**
+     * The label from `.external(label)`. Its presence is what marks the record as
+     * externally stored; the value names the binding a reader — or a model — can
+     * grep for. See `source/external.ts`.
+     */
+    external?: string;
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
@@ -56,7 +63,13 @@ export type SerializedRecordSchema = {
  * authoring.
  */
 export type JsonValuesRecordSrc<T extends Schema<SelectorSource>, K extends Schema<string>> = Record<SelectorOfSchema<K>, JsonSource<JsonOf<SelectorOfSchema<T>>> | SelectorOfSchema<T>>;
-export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | null> extends Schema<Src> {
+export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | ExternalRecordSrc | null, 
+/**
+ * Whether `.readonly()` was called. It rides in the type — not only in
+ * `isReadonly` — because `.external()` freezes it into the source marker, and
+ * the adapter's write methods are required or forbidden on the strength of it.
+ */
+RO extends boolean = false> extends Schema<Src> {
     private readonly item;
     private readonly opt;
     private readonly customValidateFunctions;
@@ -70,9 +83,31 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private readonly isJsonValues;
     private readonly previewInput;
     private readonly renderInput;
+    /**
+     * Set by `.external(label)`; the entries live behind that adapter.
+     *
+     * LAST on purpose: every other `new RecordSchema(...,
+      this.externalLabel,
+    )` in the codebase
+     * passes its arguments positionally, so a new parameter anywhere else
+     * silently shifts `previewInput` and `renderInput` at each of those call
+     * sites.
+     */
+    private readonly externalLabel;
     constructor(item: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], currentRouter?: ValRouter | null, keySchema?: Schema<string> | null, mediaOptions?: MediaOptions | undefined, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
-    isJsonValues?: boolean, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null);
+    isJsonValues?: boolean, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null, 
+    /**
+     * Set by `.external(label)`; the entries live behind that adapter.
+     *
+     * LAST on purpose: every other `new RecordSchema(...,
+      this.externalLabel,
+    )` in the codebase
+     * passes its arguments positionally, so a new parameter anywhere else
+     * silently shifts `previewInput` and `renderInput` at each of those call
+     * sites.
+     */
+    externalLabel?: string | null);
     describe(description: string | null): RecordSchema<T, K, Src>;
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -84,7 +119,17 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private validateMediaMimeType;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): RecordSchema<T, K, Src | null>;
-    readonly(isReadonly?: boolean): RecordSchema<T, K, Src>;
+    /**
+     * A record you can look at but not change.
+     *
+     * The flag rides in the TYPE as well as in the instance, so `.external()` can
+     * freeze it into the source marker and the adapter's write methods become
+     * required or forbidden on the strength of it. That is also why `.readonly()`
+     * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
+     * there is no `.readonly()` left to call — which is the error the compiler
+     * gives, and a clearer one than a runtime throw.
+     */
+    readonly<B extends boolean = true>(isReadonly?: B): RecordSchema<T, K, Src, B>;
     hidden(isHidden?: boolean): RecordSchema<T, K, Src>;
     router(router: ValRouter): RecordSchema<T, K, Src>;
     remote(): RecordSchema<T, K, Src>;
@@ -103,6 +148,37 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
      * substitution and content validation are all root-only.
      */
     jsonValues(): RecordSchema<T, K, JsonValuesRecordSrc<T, K>>;
+    /**
+     * Store this record's entries behind an adapter — a database, an HTTP API, a
+     * bucket — instead of in the module.
+     *
+     * Available on every record-derived schema, which is `s.record()`,
+     * `s.router()`, `s.images()` and `s.files()` alike: a router is a
+     * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
+     * four get external storage from this one method.
+     *
+     * `label` does not address the binding — the registry is keyed by module, and
+     * so is the wire protocol. It exists so a reader of the schema can see what
+     * backs it, and it is checked against the binding that claims it, so the two
+     * cannot drift.
+     *
+     * Only supported on a module's ROOT record, exactly as `.jsonValues()` is: a
+     * nested external record would leave a hole in the middle of a module's
+     * source, and the Studio, patching and validation all assume a module's
+     * source is complete apart from its entries.
+     */
+    external<L extends string>(label: L): RecordSchema<T, K, ExternalRecordSrc<SelectorOfSchema<T>, L, RO>, RO>;
+    /**
+     * An external record's source is either the `c.external()` marker or entries
+     * still written inline in the `.val.ts`.
+     *
+     * Inline entries are NOT a type error (see `ExternalRecordWritableSrc`), so
+     * this is where they surface: as an `external:upload` fix, per key, the way
+     * `.jsonValues()` reports an un-extracted entry. Reporting per key rather than
+     * once for the record is what lets the fix be applied to one entry, and what
+     * puts the error at a path the editor can navigate to.
+     */
+    private validateExternal;
     private getRouterValidations;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedRecordSchema;

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", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry"];
+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", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "external:upload"];
 export type ValidationFix = (typeof ValidationFix)[number];

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

@@ -12,11 +12,12 @@ import { MediaSource } from "../source/media.js";
 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 { 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 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 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 | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

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

@@ -0,0 +1,91 @@
+import { Source, VAL_EXTENSION } from "./index.js";
+/**
+ * The string used as the `_type` discriminator of an {@link ExternalRecordSrc}.
+ */
+export declare const EXTERNAL_VAL_EXTENSION_TAG: "external";
+/**
+ * Type-level-only slots. Declared here rather than reusing `PhantomType`
+ * (`source/index.ts`) because three separate facts have to ride along, and that
+ * helper carries one.
+ *
+ * None of them exist at runtime: `c.external()` produces `{ _type: "external" }`
+ * and nothing else.
+ */
+declare const ExternalItem: unique symbol;
+declare const ExternalLabel: unique symbol;
+declare const ExternalReadonly: unique symbol;
+/**
+ * The source of a record whose entries live behind an adapter — a database, an
+ * HTTP API, a bucket — instead of in the module.
+ *
+ * This is what `c.external()` returns, and it is the counterpart of the
+ * `c.json(() => import(...))` marker a `.jsonValues()` entry carries: a value
+ * that says "the content is not here" without saying anything about what is.
+ * The schema says *which* adapter (`.external("posts")`); this says *that* the
+ * entries are elsewhere, which is what every source-walking consumer needs to
+ * know without holding a schema.
+ *
+ * Three phantom parameters, each earning its place:
+ *
+ * - `T` — the item type. Without it `c.define` would return a module whose type
+ *   is "a marker", the item type would be gone, and an adapter could not be
+ *   typed from the schema at all.
+ * - `L` — the label from `.external(label)`, so a binding can be checked against
+ *   the schema that declared it.
+ * - `RO` — whether the schema said `.readonly()`, which decides whether the
+ *   adapter must implement writes or is forbidden from doing so.
+ *
+ * The defaults are the WIDEST instantiation on purpose: the bare name appears in
+ * the `Source` and `SelectorSource` unions, and every narrower instantiation has
+ * to be assignable to it. The `external()` factory below defaults the other way,
+ * exactly as `JsonSource<T = unknown>` and `json<T = Json>()` do.
+ */
+export type ExternalRecordSrc<T = unknown, L extends string = string, RO extends boolean = boolean> = {
+    readonly [VAL_EXTENSION]: typeof EXTERNAL_VAL_EXTENSION_TAG;
+} & {
+    readonly [ExternalItem]: T;
+    readonly [ExternalLabel]: L;
+    readonly [ExternalReadonly]: RO;
+};
+/**
+ * The marker written as a module's source when its record is `.external()`.
+ *
+ * Takes no arguments: everything it carries is inferred from the schema it is
+ * checked against in `c.define`. The assertion mirrors `json()` — the phantom
+ * slots are symbol-keyed and have no runtime representation, so there is nothing
+ * to construct for them.
+ */
+export declare function external<T = never, L extends string = string, RO extends boolean = false>(): ExternalRecordSrc<T, L, RO>;
+export declare function isExternal(obj: unknown): obj is ExternalRecordSrc;
+/**
+ * The item type an external record holds, read back off a module.
+ *
+ * `GenericSelector` is not imported here — that would be a cycle through
+ * `../selector` — so this is written against the phantom slot directly and the
+ * selector-shaped overloads live where the selector types do.
+ */
+export type ExternalItemOf<S> = S extends ExternalRecordSrc<infer I, string, boolean> ? I : never;
+/** The label an external record was declared with. */
+export type ExternalLabelOf<S> = S extends ExternalRecordSrc<unknown, infer L, boolean> ? L : never;
+/** Whether the schema behind an external record said `.readonly()`. */
+export type ExternalReadonlyOf<S> = S extends ExternalRecordSrc<unknown, string, infer RO> ? RO : never;
+/**
+ * The source of an external record as it may be WRITTEN.
+ *
+ * Either the marker, or entries inline in the `.val.ts`. Inline entries are
+ * accepted by the type on purpose, for the same reason `.jsonValues()` accepts
+ * them (see `JsonValuesRecordSrc`): pasting content straight into the module is
+ * the natural first thing to write, and a type error there is a dead end — the
+ * author cannot see what to write instead. Validation reports the inline entries
+ * as an `external:upload` fix instead, so the mistake is repaired rather than
+ * blocking authoring, and they are readable at runtime meanwhile.
+ */
+export type ExternalRecordWritableSrc<Item, Key extends string = string, L extends string = string, RO extends boolean = boolean> = ExternalRecordSrc<Item, L, RO> | Record<Key, Item>;
+/**
+ * Is this module source an external record that still has entries written
+ * inline? Used by validation to raise `external:upload`.
+ */
+export declare function hasInlineExternalEntries(source: Source): source is {
+    [key: string]: Source;
+};
+export {};