@valbuild/server 0.123.3 → 0.125.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @valbuild/server
 
+## 0.125.0
+
+### Patch Changes
+
+- Updated dependencies [[`c390397`](https://github.com/valbuild/val/commit/c390397cb5e203eb1bedae3a6fab15726e850b90)]:
+  - @valbuild/core@0.125.0
+  - @valbuild/shared@0.125.0
+  - @valbuild/ui@0.125.0
+
+## 0.124.0
+
+### Minor Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Show `.jsonValues()` entries in the history pane
+
+  A `.jsonValues()` record keeps each entry's content in its own `*.val.json`
+  file; the module's own content is just markers pointing at them. The history
+  pane had no way to fetch those files for a past commit, so every entry rendered
+  as an **empty field** — which reads as "the author left this blank", about
+  content that was simply stored somewhere else.
+
+  Entries now load in the history pane the same way they load in the Studio: one
+  at a time, when you open one. A commit with a thousand support pages costs
+  nothing until you look at one of them.
+
+  An entry that cannot be read says so instead of rendering blank — including the
+  case where the key did not exist yet at that commit, which is a real answer
+  rather than an error.
+
+### Patch Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Require a session to read a file from history
+
+  `GET /api/val/history/files` served a file at a given commit to anyone who
+  asked. It followed the reasoning of `/api/val/files`, which is deliberately
+  open — and neither half of that reasoning applies to it:
+
+  - `/files` stands on `patch_id` being an unguessable UUID. A **commit sha is
+    published** — `git log`, the GitHub UI, every pull request — so it is no
+    substitute for a credential.
+  - `/files` also _cannot_ require auth: draft images are fetched by the app's own
+    backend during Next image optimisation, with no cookies to send. Nothing
+    fetches history files server-side; both callers are the Studio, in a browser
+    that already holds the session.
+
+  So history files now require a session. `/files` is unchanged, and the reason
+  the two differ is written down in `architecture/media.md` so it is not "fixed"
+  in either direction later.
+
+  No action needed: the Studio sends its session cookie automatically.
+
+- Updated dependencies [[`5674237`](https://github.com/valbuild/val/commit/56742371a75b4fdcbff8b1afccff8fcc1ebf8078), [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055), [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055), [`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769)]:
+  - @valbuild/ui@0.124.0
+  - @valbuild/shared@0.124.0
+  - @valbuild/core@0.124.0
+
 ## 0.123.3
 
 ### Patch Changes

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

@@ -486,6 +486,17 @@ export declare abstract class ValOps {
     abstract getCommitAffectedFiles(commitSha: string): Promise<result.Result<AffectedFile[], HistoryError>>;
     /** One file's bytes as they were at one commit. */
     abstract getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Buffer, HistoryError>>;
+    /**
+     * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
+     *
+     * A `ModuleFilePath` is project-relative (`/app/page.val.ts`); a git path is
+     * repository-relative and carries the project root in front of it
+     * (`examples/next/app/page.val.ts`). Only the ops know that root, which is
+     * why this is here rather than computed by the history functions - and why a
+     * history function that needs to read a module's own file at a commit has to
+     * ask instead of concatenating.
+     */
+    abstract gitPathOfModule(moduleFilePath: ModuleFilePath): result.Result<string, HistoryError>;
 }
 export type WithGenericError<T extends Record<string, unknown>> = (T & {
     error?: undefined;

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

@@ -172,4 +172,5 @@ export declare class ValOpsFS extends ValOps {
     }, HistoryError>>;
     getCommitAffectedFiles(): Promise<result.Result<AffectedFile[], HistoryError>>;
     getFileAtCommit(): Promise<result.Result<Buffer, HistoryError>>;
+    gitPathOfModule(_moduleFilePath: ModuleFilePath): result.Result<string, HistoryError>;
 }

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

@@ -310,6 +310,15 @@ export declare class ValOpsHttp extends ValOps {
         complete: boolean;
     }, HistoryError>>;
     getCommitAffectedFiles(commitSha: string): Promise<result.Result<AffectedFile[], HistoryError>>;
+    /**
+     * `root` in front, and never a doubled or missing slash.
+     *
+     * `root` is "" for a project at the repository root and something like
+     * `examples/next` otherwise; a ModuleFilePath always starts with "/". Joining
+     * them by hand at each call site is how one of these ends up with "//" in the
+     * middle, which GitHub answers with a 404 that reads like a missing file.
+     */
+    gitPathOfModule(moduleFilePath: ModuleFilePath): result.Result<string, HistoryError>;
     getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Buffer, HistoryError>>;
 }
 export {};

package/dist/valbuild-server.cjs.dev.js

@@ -4118,6 +4118,17 @@ class ValOps {
 
   /** One file's bytes as they were at one commit. */
 
+  /**
+   * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
+   *
+   * A `ModuleFilePath` is project-relative (`/app/page.val.ts`); a git path is
+   * repository-relative and carries the project root in front of it
+   * (`examples/next/app/page.val.ts`). Only the ops know that root, which is
+   * why this is here rather than computed by the history functions - and why a
+   * history function that needs to read a module's own file at a commit has to
+   * ask instead of concatenating.
+   */
+
   // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
@@ -6763,6 +6774,14 @@ class ValOpsFS extends ValOps {
       kind: "not-supported-in-fs-mode"
     });
   }
+  gitPathOfModule(
+  // Unused: fs mode has no repository to be relative to. Named anyway, so
+  // this reads as the same method the base class declares.
+  _moduleFilePath) {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
   // #endregion history
 }
 class FSOpsHost {
@@ -8554,6 +8573,19 @@ class ValOpsHttp extends ValOps {
     }
     return fp.result.ok(res.value.files);
   }
+
+  /**
+   * `root` in front, and never a doubled or missing slash.
+   *
+   * `root` is "" for a project at the repository root and something like
+   * `examples/next` otherwise; a ModuleFilePath always starts with "/". Joining
+   * them by hand at each call site is how one of these ends up with "//" in the
+   * middle, which GitHub answers with a 404 that reads like a missing file.
+   */
+  gitPathOfModule(moduleFilePath) {
+    const joined = `${this.root}/${moduleFilePath}`.split("/").filter(part => part !== "").join("/");
+    return fp.result.ok(joined);
+  }
   async getFileAtCommit(commitSha, filePath, remote) {
     const params = new URLSearchParams({
       path: filePath
@@ -9013,6 +9045,129 @@ async function getModuleAtCommit(ops, commitSha, moduleFilePath) {
   });
 }
 
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (fp.result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (fp.result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, moduleRes.value.toString("utf-8"), key);
+  if (fp.result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (fp.result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (fp.result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return fp.result.ok(JSON.parse(entryRes.value.toString("utf-8")));
+  } catch (err) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts__default["default"].createSourceFile(moduleFilePath, valTsSource, ts__default["default"].ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (fp.result.isErr(analysis)) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = path__namespace["default"].posix.dirname(moduleFilePath);
+  return fp.result.ok(path__namespace["default"].posix.join(moduleDir, entry.importPath));
+}
+
 const host = process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
 const SettingsSchema = z.z.object({
   publicProjectId: z.z.string(),
@@ -12308,12 +12463,60 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    "/history/json": {
+      GET: async req => {
+        // Authenticated, for the reasons on /history/files below.
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getJsonEntryAtCommit(serverOps, req.query.commit_sha, req.query.path, req.query.key);
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        return {
+          status: 200,
+          json: {
+            path: req.query.path,
+            key: req.query.key,
+            content: res.value
+          }
+        };
+      }
+    },
     "/history/files": {
       GET: async req => {
-        // No auth, for the same reason /files has none: this is served to an
-        // <img> that the app's own backend may fetch during image
-        // optimisation, with no cookies. What it exposes is a file at a commit
-        // that is already in the repository.
+        /*
+         * Authenticated, unlike /files.
+         *
+         * This used to reason "same as /files" and that was wrong twice over.
+         * /files is open because a `patch_id` is an unguessable UUID standing
+         * in for a credential, and because it HAS to be: a draft image is
+         * fetched by the app's own backend during Next image optimisation,
+         * backend-to-backend, with no cookies to send.
+         *
+         * A commit sha is not a secret - it is in `git log`, in the GitHub UI,
+         * on every PR - so the first argument does not transfer. And nothing
+         * fetches this server-side; both callers are the Studio in a browser
+         * that has the session cookie (the history pane's <img>, and
+         * stageRestore's fetch, both same-origin so the cookie goes). So the
+         * second does not either, and there is nothing to trade away by
+         * asking.
+         */
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
         const res = await serverOps.getFileAtCommit(req.query.commit_sha, req.query.path, req.query.remote === "true");
         if (fp.result.isErr(res)) {
           const response = historyErrorResponse(res.error);
@@ -12352,6 +12555,11 @@ const ValServer = (valModules, options, callbacks) => {
         //     3) the benefit an attacker would get is an image that is not yet published (i.e. most cases: not very interesting)
         // Thus: attack surface + ease of attack + benefit = low probability of attack
         // If we couldn't argue that patch ids are secret enough, then this would be a problem.
+        // Note that /history/files, which looks like the same endpoint, IS
+        // authenticated: its token is a commit sha, which is published, and
+        // nothing fetches it backend-to-backend. Neither half of the argument
+        // above transfers. See architecture/media.md, "Why /files has no auth,
+        // and /history/files does".
         let fileBuffer;
         let mimeType;
         const remote = query.remote === "true";
@@ -14716,7 +14924,7 @@ async function handleRemoteFileUpload(ctx) {
   return uploadRemoteFileCore(ctx, fileRefProp, fileSourceMetadata, resolveRemoteFileSchema);
 }
 
-// Gallery (s.images({ remote: true }) / s.files({ remote: true })) upload.
+// Gallery (s.images({ ... }).remote() / s.files({ ... }).remote()) upload.
 // Unlike a single image/file field, a gallery entry is keyed by its local file
 // path and the value is bare metadata (no FileSource), so we derive the file
 // ref from the key and synthesize the image/file schema from the record's

package/dist/valbuild-server.cjs.prod.js

@@ -4118,6 +4118,17 @@ class ValOps {
 
   /** One file's bytes as they were at one commit. */
 
+  /**
+   * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
+   *
+   * A `ModuleFilePath` is project-relative (`/app/page.val.ts`); a git path is
+   * repository-relative and carries the project root in front of it
+   * (`examples/next/app/page.val.ts`). Only the ops know that root, which is
+   * why this is here rather than computed by the history functions - and why a
+   * history function that needs to read a module's own file at a commit has to
+   * ask instead of concatenating.
+   */
+
   // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
@@ -6763,6 +6774,14 @@ class ValOpsFS extends ValOps {
       kind: "not-supported-in-fs-mode"
     });
   }
+  gitPathOfModule(
+  // Unused: fs mode has no repository to be relative to. Named anyway, so
+  // this reads as the same method the base class declares.
+  _moduleFilePath) {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
   // #endregion history
 }
 class FSOpsHost {
@@ -8554,6 +8573,19 @@ class ValOpsHttp extends ValOps {
     }
     return fp.result.ok(res.value.files);
   }
+
+  /**
+   * `root` in front, and never a doubled or missing slash.
+   *
+   * `root` is "" for a project at the repository root and something like
+   * `examples/next` otherwise; a ModuleFilePath always starts with "/". Joining
+   * them by hand at each call site is how one of these ends up with "//" in the
+   * middle, which GitHub answers with a 404 that reads like a missing file.
+   */
+  gitPathOfModule(moduleFilePath) {
+    const joined = `${this.root}/${moduleFilePath}`.split("/").filter(part => part !== "").join("/");
+    return fp.result.ok(joined);
+  }
   async getFileAtCommit(commitSha, filePath, remote) {
     const params = new URLSearchParams({
       path: filePath
@@ -9013,6 +9045,129 @@ async function getModuleAtCommit(ops, commitSha, moduleFilePath) {
   });
 }
 
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (fp.result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (fp.result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, moduleRes.value.toString("utf-8"), key);
+  if (fp.result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (fp.result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (fp.result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return fp.result.ok(JSON.parse(entryRes.value.toString("utf-8")));
+  } catch (err) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts__default["default"].createSourceFile(moduleFilePath, valTsSource, ts__default["default"].ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (fp.result.isErr(analysis)) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = path__namespace["default"].posix.dirname(moduleFilePath);
+  return fp.result.ok(path__namespace["default"].posix.join(moduleDir, entry.importPath));
+}
+
 const host = process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
 const SettingsSchema = z.z.object({
   publicProjectId: z.z.string(),
@@ -12308,12 +12463,60 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    "/history/json": {
+      GET: async req => {
+        // Authenticated, for the reasons on /history/files below.
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getJsonEntryAtCommit(serverOps, req.query.commit_sha, req.query.path, req.query.key);
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        return {
+          status: 200,
+          json: {
+            path: req.query.path,
+            key: req.query.key,
+            content: res.value
+          }
+        };
+      }
+    },
     "/history/files": {
       GET: async req => {
-        // No auth, for the same reason /files has none: this is served to an
-        // <img> that the app's own backend may fetch during image
-        // optimisation, with no cookies. What it exposes is a file at a commit
-        // that is already in the repository.
+        /*
+         * Authenticated, unlike /files.
+         *
+         * This used to reason "same as /files" and that was wrong twice over.
+         * /files is open because a `patch_id` is an unguessable UUID standing
+         * in for a credential, and because it HAS to be: a draft image is
+         * fetched by the app's own backend during Next image optimisation,
+         * backend-to-backend, with no cookies to send.
+         *
+         * A commit sha is not a secret - it is in `git log`, in the GitHub UI,
+         * on every PR - so the first argument does not transfer. And nothing
+         * fetches this server-side; both callers are the Studio in a browser
+         * that has the session cookie (the history pane's <img>, and
+         * stageRestore's fetch, both same-origin so the cookie goes). So the
+         * second does not either, and there is nothing to trade away by
+         * asking.
+         */
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
         const res = await serverOps.getFileAtCommit(req.query.commit_sha, req.query.path, req.query.remote === "true");
         if (fp.result.isErr(res)) {
           const response = historyErrorResponse(res.error);
@@ -12352,6 +12555,11 @@ const ValServer = (valModules, options, callbacks) => {
         //     3) the benefit an attacker would get is an image that is not yet published (i.e. most cases: not very interesting)
         // Thus: attack surface + ease of attack + benefit = low probability of attack
         // If we couldn't argue that patch ids are secret enough, then this would be a problem.
+        // Note that /history/files, which looks like the same endpoint, IS
+        // authenticated: its token is a commit sha, which is published, and
+        // nothing fetches it backend-to-backend. Neither half of the argument
+        // above transfers. See architecture/media.md, "Why /files has no auth,
+        // and /history/files does".
         let fileBuffer;
         let mimeType;
         const remote = query.remote === "true";
@@ -14716,7 +14924,7 @@ async function handleRemoteFileUpload(ctx) {
   return uploadRemoteFileCore(ctx, fileRefProp, fileSourceMetadata, resolveRemoteFileSchema);
 }
 
-// Gallery (s.images({ remote: true }) / s.files({ remote: true })) upload.
+// Gallery (s.images({ ... }).remote() / s.files({ ... }).remote()) upload.
 // Unlike a single image/file field, a gallery entry is keyed by its local file
 // path and the value is bare metadata (no FileSource), so we derive the file
 // ref from the key and synthesize the image/file schema from the record's

package/dist/valbuild-server.esm.js

@@ -4084,6 +4084,17 @@ class ValOps {
 
   /** One file's bytes as they were at one commit. */
 
+  /**
+   * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
+   *
+   * A `ModuleFilePath` is project-relative (`/app/page.val.ts`); a git path is
+   * repository-relative and carries the project root in front of it
+   * (`examples/next/app/page.val.ts`). Only the ops know that root, which is
+   * why this is here rather than computed by the history functions - and why a
+   * history function that needs to read a module's own file at a commit has to
+   * ask instead of concatenating.
+   */
+
   // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
@@ -6729,6 +6740,14 @@ class ValOpsFS extends ValOps {
       kind: "not-supported-in-fs-mode"
     });
   }
+  gitPathOfModule(
+  // Unused: fs mode has no repository to be relative to. Named anyway, so
+  // this reads as the same method the base class declares.
+  _moduleFilePath) {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
   // #endregion history
 }
 class FSOpsHost {
@@ -8520,6 +8539,19 @@ class ValOpsHttp extends ValOps {
     }
     return result.ok(res.value.files);
   }
+
+  /**
+   * `root` in front, and never a doubled or missing slash.
+   *
+   * `root` is "" for a project at the repository root and something like
+   * `examples/next` otherwise; a ModuleFilePath always starts with "/". Joining
+   * them by hand at each call site is how one of these ends up with "//" in the
+   * middle, which GitHub answers with a 404 that reads like a missing file.
+   */
+  gitPathOfModule(moduleFilePath) {
+    const joined = `${this.root}/${moduleFilePath}`.split("/").filter(part => part !== "").join("/");
+    return result.ok(joined);
+  }
   async getFileAtCommit(commitSha, filePath, remote) {
     const params = new URLSearchParams({
       path: filePath
@@ -8979,6 +9011,129 @@ async function getModuleAtCommit(ops, commitSha, moduleFilePath) {
   });
 }
 
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, moduleRes.value.toString("utf-8"), key);
+  if (result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return result.ok(JSON.parse(entryRes.value.toString("utf-8")));
+  } catch (err) {
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts.createSourceFile(moduleFilePath, valTsSource, ts.ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (result.isErr(analysis)) {
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = path__default.posix.dirname(moduleFilePath);
+  return result.ok(path__default.posix.join(moduleDir, entry.importPath));
+}
+
 const host = process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST;
 const SettingsSchema = z.object({
   publicProjectId: z.string(),
@@ -12274,12 +12429,60 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    "/history/json": {
+      GET: async req => {
+        // Authenticated, for the reasons on /history/files below.
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getJsonEntryAtCommit(serverOps, req.query.commit_sha, req.query.path, req.query.key);
+        if (result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        return {
+          status: 200,
+          json: {
+            path: req.query.path,
+            key: req.query.key,
+            content: res.value
+          }
+        };
+      }
+    },
     "/history/files": {
       GET: async req => {
-        // No auth, for the same reason /files has none: this is served to an
-        // <img> that the app's own backend may fetch during image
-        // optimisation, with no cookies. What it exposes is a file at a commit
-        // that is already in the repository.
+        /*
+         * Authenticated, unlike /files.
+         *
+         * This used to reason "same as /files" and that was wrong twice over.
+         * /files is open because a `patch_id` is an unguessable UUID standing
+         * in for a credential, and because it HAS to be: a draft image is
+         * fetched by the app's own backend during Next image optimisation,
+         * backend-to-backend, with no cookies to send.
+         *
+         * A commit sha is not a secret - it is in `git log`, in the GitHub UI,
+         * on every PR - so the first argument does not transfer. And nothing
+         * fetches this server-side; both callers are the Studio in a browser
+         * that has the session cookie (the history pane's <img>, and
+         * stageRestore's fetch, both same-origin so the cookie goes). So the
+         * second does not either, and there is nothing to trade away by
+         * asking.
+         */
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
         const res = await serverOps.getFileAtCommit(req.query.commit_sha, req.query.path, req.query.remote === "true");
         if (result.isErr(res)) {
           const response = historyErrorResponse(res.error);
@@ -12318,6 +12521,11 @@ const ValServer = (valModules, options, callbacks) => {
         //     3) the benefit an attacker would get is an image that is not yet published (i.e. most cases: not very interesting)
         // Thus: attack surface + ease of attack + benefit = low probability of attack
         // If we couldn't argue that patch ids are secret enough, then this would be a problem.
+        // Note that /history/files, which looks like the same endpoint, IS
+        // authenticated: its token is a commit sha, which is published, and
+        // nothing fetches it backend-to-backend. Neither half of the argument
+        // above transfers. See architecture/media.md, "Why /files has no auth,
+        // and /history/files does".
         let fileBuffer;
         let mimeType;
         const remote = query.remote === "true";
@@ -14682,7 +14890,7 @@ async function handleRemoteFileUpload(ctx) {
   return uploadRemoteFileCore(ctx, fileRefProp, fileSourceMetadata, resolveRemoteFileSchema);
 }
 
-// Gallery (s.images({ remote: true }) / s.files({ remote: true })) upload.
+// Gallery (s.images({ ... }).remote() / s.files({ ... }).remote()) upload.
 // Unlike a single image/file field, a gallery entry is keyed by its local file
 // path and the value is bare metadata (no FileSource), so we derive the file
 // ref from the key and synthesize the image/file schema from the record's

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.123.3",
+  "version": "0.125.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.121.0",
-    "@valbuild/ui": "0.123.3",
-    "@valbuild/shared": "0.123.3"
+    "@valbuild/core": "0.125.0",
+    "@valbuild/shared": "0.125.0",
+    "@valbuild/ui": "0.125.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22"