@valbuild/server 0.99.1 → 0.101.0

package/dist/valbuild-server.esm.js

@@ -1,7 +1,7 @@
 import ts from 'typescript';
-import { result, pipe } from '@valbuild/core/fp';
-import { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG, VAL_EXTENSION, derefPatch, extractValModules, Internal, ImageSchema, DEFAULT_CONTENT_HOST } from '@valbuild/core';
-import { deepEqual, isNotRoot, PatchError, parseAndValidateArrayIndex, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
+import { pipe, result, array } from '@valbuild/core/fp';
+import { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG, VAL_EXTENSION, derefPatch, RecordSchema, Internal, extractValModules, ImageSchema, DEFAULT_CONTENT_HOST } from '@valbuild/core';
+import { PatchError, deepEqual, parseAndValidateArrayIndex, isNotRoot, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
 import * as path from 'path';
 import path__default from 'path';
 import fs, { promises } from 'fs';
@@ -345,6 +345,65 @@ function createValRemoteReference(value) {
   }
   return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("c"), ts.factory.createIdentifier("remote")), undefined, args);
 }
+
+/**
+ * Builds the expression `c.json(() => import("<importPath>"))` used to reference
+ * a lazily-loaded `*.val.json` entry of a `.jsonValues()` record.
+ */
+function createValJsonReference(importPath) {
+  // () => import("<importPath>")
+  // NOTE: an `import` identifier prints as the dynamic-import keyword call,
+  // which avoids casting the ImportKeyword token (not typed as an Expression).
+  const importCall = ts.factory.createCallExpression(ts.factory.createIdentifier("import"), undefined, [ts.factory.createStringLiteral(importPath)]);
+  const thunk = ts.factory.createArrowFunction(undefined, undefined, [], undefined, ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), importCall);
+  // c.json(<thunk>)
+  return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("c"), ts.factory.createIdentifier("json")), undefined, [thunk]);
+}
+
+/**
+ * Inserts a new `.jsonValues()` entry `"<key>": c.json(() => import("<importPath>"))`
+ * into the record's object literal in a `.val.ts` module. `recordPath` is the
+ * path from the module source to the record (empty for a root record/router).
+ * Fails if the entry key already exists.
+ */
+function insertValJsonEntry(document, recordPath, key, importPath) {
+  return pipe(analyzeValModule(document), result.flatMap(({
+    source
+  }) => getAtPath(source, recordPath)), result.flatMap(recordNode => {
+    if (!ts.isObjectLiteralExpression(recordNode)) {
+      return result.err(new PatchError("Cannot add jsonValues entry: record source is not an object literal"));
+    }
+    return pipe(findObjectPropertyAssignment(recordNode, key), result.flatMap(assignment => {
+      if (assignment) {
+        return result.err(new PatchError(`Cannot add jsonValues entry '${key}': it already exists`));
+      }
+      const property = ts.factory.createPropertyAssignment(isValidIdentifier(key) ? ts.factory.createIdentifier(key) : ts.factory.createStringLiteral(key), createValJsonReference(importPath));
+      return result.ok(insertAt(document, recordNode.properties, recordNode.properties.length, property));
+    }));
+  }));
+}
+
+/**
+ * Removes the `.jsonValues()` entry `"<key>"` from the record's object literal
+ * in a `.val.ts` module. `recordPath` is the path from the module source to the
+ * record (empty for a root record/router). Fails if the entry key is missing.
+ */
+function removeValJsonEntry(document, recordPath, key) {
+  return pipe(analyzeValModule(document), result.flatMap(({
+    source
+  }) => getAtPath(source, recordPath)), result.flatMap(recordNode => {
+    if (!ts.isObjectLiteralExpression(recordNode)) {
+      return result.err(new PatchError("Cannot remove jsonValues entry: record source is not an object literal"));
+    }
+    return pipe(findObjectPropertyAssignment(recordNode, key), result.flatMap(assignment => {
+      if (!assignment) {
+        return result.err(new PatchError(`Cannot remove jsonValues entry '${key}': it does not exist`));
+      }
+      const [doc] = removeAt(document, recordNode.properties, recordNode.properties.indexOf(assignment));
+      return result.ok(doc);
+    }));
+  }));
+}
 function toExpression(value) {
   if (typeof value === "string") {
     // TODO: Use configuration/heuristics to determine use of single quote or double quote
@@ -979,7 +1038,7 @@ function findValModulesPath(projectRoot, host) {
   }
   return null;
 }
-const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs"];
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs", ".json"];
 
 // Specifiers that user val files must not actually use. We stub them so that
 // importing is fine, but using a value throws a clear error. Real @valbuild
@@ -1019,6 +1078,27 @@ function loadModule(absPath, cache, compilerOptions, host) {
   if (cached) {
     return cached;
   }
+  // JSON modules (e.g. the `*.val.json` files backing `.jsonValues()` entries)
+  // are loaded by parsing, mirroring Node's `require("./x.json")` which returns
+  // the parsed object as `module.exports`. The importing `.val.ts` wraps this
+  // with `__importStar` so `import("./x.val.json")` yields `{ default, ... }`.
+  // These are only loaded when an entry thunk is invoked, never during
+  // `extractValModules`, so this stays lazy.
+  //
+  // Read through `host` like every other project file: an editor integration
+  // passes a host that overlays unsaved buffers, and an entry the user is
+  // editing has to resolve to what they are looking at.
+  if (absPath.endsWith(".json")) {
+    const json = host.readFile(absPath);
+    if (json === undefined) {
+      throw Error(`Could not read Val module file: '${absPath}'`);
+    }
+    const jsonModule = {
+      exports: JSON.parse(json)
+    };
+    cache[absPath] = jsonModule;
+    return jsonModule;
+  }
   const code = host.readFile(absPath);
   if (code === undefined) {
     throw Error(`Could not read Val module file: '${absPath}'`);
@@ -1107,6 +1187,403 @@ function resolveRelative(dirName, spec, host) {
   return null;
 }
 
+const jsonOps$1 = new JSONOps();
+
+/**
+ * Classification of a single patch op against a module's serialized schema,
+ * used by the commit flow to route ops for `.jsonValues()` records:
+ *
+ * - `normal`: the op does not descend into a `.jsonValues()` entry; apply it to
+ *   the `.val.ts` as usual.
+ * - `entry`: the op targets a `.jsonValues()` entry. `recordPath` is the path to
+ *   the record within the module source (empty for a root record/router),
+ *   `entryKey` is the entry key, and `subPath` is the remaining path inside the
+ *   entry (empty when the op targets the entry value itself, e.g. add/remove of
+ *   the whole entry).
+ */
+
+/**
+ * Walks the serialized schema following the op path. When a `.jsonValues()`
+ * record is encountered, the next path segment is the entry key and everything
+ * after it lives inside the entry's `*.val.json` (so it does not touch the
+ * `.val.ts`). Returns `{ kind: "normal" }` when the op never enters a
+ * `.jsonValues()` record.
+ */
+function classifyJsonValuesOp(schema, opPath) {
+  let current = schema;
+  const recordPath = [];
+  for (let i = 0; i < opPath.length; i++) {
+    if (!current) {
+      return {
+        kind: "normal"
+      };
+    }
+    if (current.type === "record" && current.jsonValues) {
+      return {
+        kind: "entry",
+        recordPath: recordPath.slice(),
+        entryKey: opPath[i],
+        subPath: opPath.slice(i + 1)
+      };
+    }
+    const seg = opPath[i];
+    current = descend(current, seg);
+    recordPath.push(seg);
+  }
+  return {
+    kind: "normal"
+  };
+}
+function descend(schema, key) {
+  switch (schema.type) {
+    case "object":
+      return schema.items[key];
+    case "record":
+      return schema.item;
+    case "array":
+      return schema.item;
+    default:
+      // Unions / primitives / leaf schemas: we cannot (or need not) descend
+      // further to find a jsonValues record. Anything below is a normal
+      // `.val.ts` edit.
+      return undefined;
+  }
+}
+
+/**
+ * Finds every `.jsonValues()` record in a module's schema that is NOT the
+ * module's root, returning the path to each within the module source.
+ *
+ * `.jsonValues()` is only supported on a module's ROOT record/router: the
+ * `/json` endpoint keys entries by a single string, the Studio substitutes
+ * loaded content at the top level of the module source, and
+ * `validateJsonValuesEntries` only visits a root record. A nested one would
+ * silently skip content validation and hang the Studio on a 404, so we reject
+ * it up front instead (see {@link ValOps.initSources}).
+ */
+function findNestedJsonValuesRecords(schema, path = []) {
+  const found = [];
+  const rec = (current, currentPath) => {
+    if (current.type === "record" && current.jsonValues && currentPath.length > 0) {
+      found.push(currentPath);
+      // Do not descend: everything below lives in the entry's `*.val.json`.
+      return;
+    }
+    switch (current.type) {
+      case "object":
+        for (const key of Object.keys(current.items)) {
+          rec(current.items[key], currentPath.concat(key));
+        }
+        return;
+      case "record":
+        rec(current.item, currentPath.concat("*"));
+        return;
+      case "array":
+        rec(current.item, currentPath.concat("*"));
+        return;
+      case "union":
+        for (let i = 0; i < current.items.length; i++) {
+          rec(current.items[i], currentPath.concat(`union[${i}]`));
+        }
+        return;
+      default:
+        return;
+    }
+  };
+  rec(schema, path);
+  return found;
+}
+
+/**
+ * The `.val.ts` suffix a module file path ends with. Stripping it yields the
+ * folder that a new entry's `*.val.json` files are nested under.
+ */
+const VAL_TS_SUFFIX = ".val.ts";
+
+/**
+ * Computes the `*.val.json` file path (relative to rootDir) and the `import(...)`
+ * path (relative to the module's directory) for a NEW `.jsonValues()` entry,
+ * following the locked filename convention: the file mirrors the entry key under
+ * a folder named after the `.val.ts` (its `.val.ts` suffix becomes the folder).
+ *
+ * For module `/app/support/[slug]/page.val.ts` and key `/support/faq`:
+ * - jsonPath:   `/app/support/[slug]/page/support/faq.val.json`
+ * - importPath: `./page/support/faq.val.json`
+ */
+function getNewJsonEntryPaths(moduleFilePath, entryKey) {
+  const base = moduleFilePath.endsWith(VAL_TS_SUFFIX) ? moduleFilePath.slice(0, -VAL_TS_SUFFIX.length) : moduleFilePath;
+  const keyRel = entryKey.replace(/^\//, "");
+  const invalid = reason => result.err({
+    message: `Invalid .jsonValues() entry key '${entryKey}' in ${moduleFilePath}: ${reason}`,
+    filePath: moduleFilePath
+  });
+  // An entry key is CLIENT-SUPPLIED — it arrives as a record key in a patch op —
+  // and this path is what the commit writes to disk. Left unchecked, a key with
+  // `..` segments (or a backslash, which is a separator once the path is handed
+  // to node's `path.join` on Windows) puts that write anywhere in the project or
+  // outside it entirely, and a `move` additionally deletes the source path.
+  if (keyRel === "") {
+    return invalid("it is empty");
+  }
+  if (keyRel.includes("\\") || keyRel.includes("\0")) {
+    return invalid("it contains a backslash or a NUL byte");
+  }
+  const jsonPath = path.posix.normalize(`${base}/${keyRel}.val.json`);
+  if (!jsonPath.startsWith(`${base}/`)) {
+    return invalid(`it resolves outside '${base}/'`);
+  }
+  const moduleDir = path.posix.dirname(moduleFilePath);
+  let importPath = path.posix.relative(moduleDir, jsonPath);
+  if (!importPath.startsWith(".")) {
+    importPath = `./${importPath}`;
+  }
+  return result.ok({
+    jsonPath,
+    importPath
+  });
+}
+
+/**
+ * Rebases a patch op that targets a `.jsonValues()` entry's content so its paths
+ * are relative to the entry's `*.val.json` root (drops the record + entry-key
+ * prefix). Used to replay the op against the backing JSON file.
+ */
+function rebaseContentOp(op, prefixLen) {
+  const path = op.path.slice(prefixLen);
+  switch (op.op) {
+    case "add":
+    case "replace":
+    case "test":
+      return result.ok({
+        ...op,
+        path
+      });
+    case "remove":
+      {
+        if (!array.isNonEmpty(path)) {
+          return result.err(new PatchError("Cannot remove the root of a jsonValues entry"));
+        }
+        return result.ok({
+          ...op,
+          path
+        });
+      }
+    case "move":
+      {
+        const from = op.from.slice(prefixLen);
+        if (!array.isNonEmpty(from)) {
+          return result.err(new PatchError("Cannot move from the root of a jsonValues entry"));
+        }
+        return result.ok({
+          ...op,
+          path,
+          from
+        });
+      }
+    case "copy":
+      return result.ok({
+        ...op,
+        path,
+        from: op.from.slice(prefixLen)
+      });
+    case "file":
+      return result.err(new PatchError("Cannot apply a file op to a jsonValues entry"));
+  }
+}
+
+/** The outcome of replaying pending patches onto one `.jsonValues()` entry. */
+
+/**
+ * Replays the ops of `patches` that target ONE `.jsonValues()` entry onto its
+ * committed content, yielding the entry's draft content.
+ *
+ * This is the read-side counterpart to the commit flow in `ValOps.prepare`:
+ * both route ops with {@link classifyJsonValuesOp} and replay content sub-ops
+ * with {@link rebaseContentOp}, but this one produces a value instead of files
+ * and never touches the `.val.ts`.
+ *
+ * Root-only, like the rest of the `.jsonValues()` machinery: ops targeting a
+ * nested record are ignored (nested `.jsonValues()` is rejected at startup).
+ */
+function applyJsonValuesEntryPatches(args) {
+  const {
+    serializedSchema,
+    entryKey,
+    baseContent,
+    patches
+  } = args;
+  let content = baseContent;
+  let deleted = false;
+  const appliedPatchIds = [];
+  for (const {
+    patchId,
+    patch
+  } of patches) {
+    let touched = false;
+    for (const op of patch) {
+      if (op.op === "file") {
+        continue;
+      }
+      const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+        kind: "normal"
+      };
+      if (cls.kind !== "entry" || cls.recordPath.length > 0 || cls.entryKey !== entryKey) {
+        continue;
+      }
+      touched = true;
+      if (cls.subPath.length === 0) {
+        if (op.op === "add" || op.op === "replace") {
+          content = op.value;
+          deleted = false;
+        } else if (op.op === "remove") {
+          content = undefined;
+          deleted = true;
+        } else if (op.op === "test") {
+          // An assertion, not a mutation: the content is unchanged either way, and
+          // the commit path is where a failing `test` is reported. Falling through
+          // to the move/copy error below turned a no-op into a permanent load
+          // failure for the whole entry.
+          continue;
+        } else {
+          // move/copy INTO this key: the content comes from the source entry,
+          // which the caller must resolve (it is a different `*.val.json`).
+          return {
+            kind: "error",
+            message: `Cannot resolve '${op.op}' of jsonValues entry '${entryKey}' from its own content`,
+            patchId
+          };
+        }
+        continue;
+      }
+      if (content === undefined) {
+        return {
+          kind: "error",
+          message: `Cannot edit jsonValues entry '${entryKey}': it does not exist`,
+          patchId
+        };
+      }
+      const rebased = rebaseContentOp(op, cls.recordPath.length + 1);
+      if (result.isErr(rebased)) {
+        return {
+          kind: "error",
+          message: rebased.error.message,
+          patchId
+        };
+      }
+      const applied = applyPatch(deepClone(content), jsonOps$1, [rebased.value]);
+      if (result.isErr(applied)) {
+        return {
+          kind: "error",
+          message: applied.error.message,
+          patchId
+        };
+      }
+      content = applied.value;
+    }
+    if (touched) {
+      appliedPatchIds.push(patchId);
+    }
+  }
+  if (deleted || content === undefined) {
+    return {
+      kind: "deleted",
+      appliedPatchIds
+    };
+  }
+  return {
+    kind: "content",
+    content,
+    appliedPatchIds
+  };
+}
+
+/**
+ * Resolves an EXISTING entry's `*.val.json` path (relative to rootDir) from the
+ * `import(...)` path recorded in the `.val.ts` thunk (from
+ * {@link analyzeJsonValuesEntries}). Existing files may have been hand-placed,
+ * so the import path is authoritative (hybrid authoring).
+ */
+function resolveExistingJsonPath(moduleFilePath, importPath) {
+  const moduleDir = path.posix.dirname(moduleFilePath);
+  return path.posix.join(moduleDir, importPath);
+}
+
+/**
+ * Validates the content of every `.jsonValues()` entry in a module by loading
+ * each backing `*.val.json` (via its lazy import thunk) and checking it against
+ * the record's item schema.
+ *
+ * The record-level `executeValidate` only asserts the marker shape — content
+ * validation is deferred (the content isn't inlined). This performs that
+ * deferred deep validation server-side. Every loadable entry is validated;
+ * validation is allowed to be slower at scale, so a sha-keyed skip-cache is left
+ * as a later optimization.
+ *
+ * Entries without a runtime import thunk (transport markers / draft entries
+ * whose content lives in a patch) are skipped here — their content is validated
+ * where it is loaded (the single-entry fetch path).
+ *
+ * ROOT-ONLY BY CONTRACT: only a module whose root schema is a `.jsonValues()`
+ * record is visited. Nested `.jsonValues()` records are rejected up front as
+ * module errors (see `findNestedJsonValuesRecords`), so they can never reach
+ * here — if that guard is ever relaxed, this must become a recursive visitor or
+ * nested entries silently get no content validation at all.
+ */
+async function validateJsonValuesEntries(schema, source, modulePath) {
+  const out = {};
+  if (!(schema instanceof RecordSchema)) {
+    return out;
+  }
+  if (!schema["executeSerialize"]().jsonValues) {
+    return out;
+  }
+  if (source === null || typeof source !== "object" || Array.isArray(source)) {
+    return out;
+  }
+  for (const [key, marker] of Object.entries(source)) {
+    const entryPath = Internal.createValPathOfItem(modulePath, key);
+    if (!entryPath) {
+      continue;
+    }
+    if (!Internal.isJson(marker)) {
+      // A value written INLINE in the `.val.ts` instead of `c.json(() => import(...))`.
+      //
+      // The record-level validation checks it against the item schema (so bad
+      // content is still reported), but it cannot report the inlining itself:
+      // the Studio substitutes loaded entry content in place of the marker
+      // before validating, so from `executeValidate`'s perspective a loaded
+      // entry and a hand-authored one look identical. Here the source is the
+      // module as it is on disk, where a non-marker can only be inlined.
+      out[entryPath] = [{
+        message: `Entry '${key}' is written inline in ${modulePath}, but this record uses .jsonValues(): entry values must live in their own '*.val.json' file, referenced with c.json(() => import("./...")). Run 'val validate --fix' to move it.`,
+        value: marker,
+        fixes: ["jsonValues:extract-entry"]
+      }];
+      continue;
+    }
+    const thunk = Internal.getJsonImport(marker);
+    if (!thunk) {
+      continue;
+    }
+    let content;
+    try {
+      content = (await thunk()).default;
+    } catch (err) {
+      out[entryPath] = [{
+        message: `Could not load JSON entry '${key}': ${err instanceof Error ? err.message : String(err)}`
+      }];
+      continue;
+    }
+    const entryErrors = schema.validateJsonEntryContent(entryPath, content);
+    if (entryErrors) {
+      for (const [p, errs] of Object.entries(entryErrors)) {
+        out[p] = errs;
+      }
+    }
+  }
+  return out;
+}
+
 async function createService(projectRoot, host = {
   ...ts.sys,
   writeFile: (fileName, data, encoding) => {
@@ -1174,10 +1651,48 @@ class Service {
         }
       };
     }
-    const validation = opts.validate ? schema["executeValidate"](moduleFilePath, source) : false;
+    let validation = opts.validate ? schema["executeValidate"](moduleFilePath, source) : false;
+
+    // `.jsonValues()` needs two checks that `executeValidate` structurally
+    // cannot do, and this is the ONLY place the Service-based callers (the CLI's
+    // `val validate`, chiefly) can get them. `ValOps` — the Studio's path — has
+    // its own copies; without these, `val validate` reports a module with broken
+    // entry content, or an unsupported nested `.jsonValues()`, as VALID, and CI
+    // gates on that.
+    let jsonValuesModuleError;
+    if (opts.validate) {
+      const nested = findNestedJsonValuesRecords(serializedSchema);
+      if (nested.length > 0) {
+        // Root-only is a hard contract (see findNestedJsonValuesRecords): a
+        // nested one would silently get NO content validation, which is exactly
+        // the failure this check exists to prevent.
+        jsonValuesModuleError = `Nested .jsonValues() records are not supported: ${nested.map(nestedPath => `'${nestedPath.join(".")}'`).join(", ")} in ${moduleFilePath}. Use .jsonValues() only on a module's root record/router.`;
+      } else {
+        // Loads every entry's backing `*.val.json` through its thunk. That is the
+        // accepted cost of having no revalidation token (locked decision #3):
+        // validation is allowed to be slower at scale, but it is not allowed to
+        // silently skip content.
+        const entryErrors = await validateJsonValuesEntries(schema, source, moduleFilePath);
+        if (Object.keys(entryErrors).length > 0) {
+          // Concatenate per path, never overwrite: an entry written inline is
+          // reported BOTH by the record-level validation (which checks the
+          // inline value against the item schema) and here (which reports the
+          // inlining itself). A spread would drop whichever came first, hiding
+          // a real content error behind the inlining error or vice versa.
+          const merged = {
+            ...(validation || {})
+          };
+          for (const [entryPathS, errs] of Object.entries(entryErrors)) {
+            const entryPath = entryPathS;
+            merged[entryPath] = (merged[entryPath] || []).concat(errs);
+          }
+          validation = merged;
+        }
+      }
+    }
     const resolved = Internal.resolvePath(modulePath, source, serializedSchema);
     const sourcePath = resolved.path ? [moduleFilePath, resolved.path].join(".") : moduleFilePath;
-    if (!validation && !moduleError) {
+    if (!validation && !moduleError && !jsonValuesModuleError) {
       return {
         path: sourcePath,
         source: resolved.source,
@@ -1185,15 +1700,24 @@ class Service {
         errors: false
       };
     }
+    const fatal = [];
+    if (moduleError) {
+      fatal.push({
+        message: moduleError.message
+      });
+    }
+    if (jsonValuesModuleError) {
+      fatal.push({
+        message: jsonValuesModuleError
+      });
+    }
     return {
       path: sourcePath,
       source: resolved.source,
       schema: resolved.schema,
       errors: {
         validation: validation || undefined,
-        fatal: moduleError ? [{
-          message: moduleError.message
-        }] : undefined
+        fatal: fatal.length > 0 ? fatal : undefined
       }
     };
   }
@@ -1263,6 +1787,92 @@ function encodeJwt(payload, sessionKey) {
   return `${jwtHeaderBase64}.${payloadBase64}.${crypto$1.createHmac("sha256", sessionKey).update(`${jwtHeaderBase64}.${payloadBase64}`).digest("base64")}`;
 }
 
+/**
+ * Given the `source` object-literal expression of a `.jsonValues()` record /
+ * router (the 3rd argument to `c.define`, via {@link analyzeValModule}),
+ * extracts each entry's `c.json(() => import("..."))` import path, keyed by
+ * entry key. Entries whose value is not a `c.json(...)` call are skipped.
+ */
+function analyzeJsonValuesEntries(source) {
+  const entries = new Map();
+  if (!ts.isObjectLiteralExpression(source)) {
+    return entries;
+  }
+  for (const prop of source.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue;
+    }
+    const key = getPropertyKey(prop.name);
+    if (key === null) {
+      continue;
+    }
+    const entry = analyzeCJsonCall(prop.initializer);
+    if (entry) {
+      entries.set(key, entry);
+    }
+  }
+  return entries;
+}
+function getPropertyKey(name) {
+  if (ts.isStringLiteralLike(name)) {
+    return name.text;
+  }
+  if (ts.isIdentifier(name)) {
+    return name.text;
+  }
+  return null;
+}
+function analyzeCJsonCall(node) {
+  // c.json(() => import("path"))
+  if (!ts.isCallExpression(node) || !isCJson(node.expression)) {
+    return null;
+  }
+  const [thunk] = node.arguments;
+  if (!thunk) {
+    return null;
+  }
+  const importPath = getImportPathFromThunk(thunk);
+  if (importPath === null) {
+    return null;
+  }
+  return {
+    importPath
+  };
+}
+function isCJson(expr) {
+  // c.json
+  return ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression) && expr.expression.text === "c" && ts.isIdentifier(expr.name) && expr.name.text === "json";
+}
+function getImportPathFromThunk(thunk) {
+  // () => import("path")   (concise body)   OR   () => { return import("path"); }
+  if (!ts.isArrowFunction(thunk)) {
+    return null;
+  }
+  let importCall;
+  if (ts.isCallExpression(thunk.body)) {
+    importCall = thunk.body;
+  } else if (ts.isBlock(thunk.body)) {
+    for (const stmt of thunk.body.statements) {
+      if (ts.isReturnStatement(stmt) && stmt.expression && ts.isCallExpression(stmt.expression)) {
+        importCall = stmt.expression;
+        break;
+      }
+    }
+  }
+  if (!importCall || !ts.isCallExpression(importCall)) {
+    return null;
+  }
+  const isImport = importCall.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(importCall.expression) && importCall.expression.text === "import";
+  if (!isImport) {
+    return null;
+  }
+  const arg = importCall.arguments[0];
+  if (arg && ts.isStringLiteralLike(arg)) {
+    return arg.text;
+  }
+  return null;
+}
+
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const jsonOps = new JSONOps();
 const tsOps = new TSOps(document => {
@@ -1270,6 +1880,38 @@ const tsOps = new TSOps(document => {
     source
   }) => source));
 });
+
+/**
+ * `.jsonValues()` is only supported on a module's ROOT record/router. A nested
+ * one is broken end to end (the `/json` endpoint keys entries by a single
+ * string, the Studio substitutes at the top level, and content validation
+ * silently skips it), so reject it up front as a module error — `/sources/~`
+ * then fails with "Val is not correctly setup" naming the module.
+ */
+function findNestedJsonValuesModuleErrors(schemas) {
+  const errors = [];
+  for (const moduleFilePathS of Object.keys(schemas)) {
+    const moduleFilePath = moduleFilePathS;
+    const schema = schemas[moduleFilePath];
+    if (!schema) {
+      continue;
+    }
+    let serialized;
+    try {
+      serialized = schema["executeSerialize"]();
+    } catch {
+      // Serialization errors are reported elsewhere (e.g. by extractValModules).
+      continue;
+    }
+    for (const nestedPath of findNestedJsonValuesRecords(serialized)) {
+      errors.push({
+        path: moduleFilePath,
+        message: `Nested .jsonValues() records are not supported: '${nestedPath.join(".")}' in ${moduleFilePath}. Use .jsonValues() only on a module's root record/router.`
+      });
+    }
+  }
+  return errors;
+}
 // #region ValOps
 class ValOps {
   /** Sources from val modules, immutable (without patches or anything)  */
@@ -1311,13 +1953,14 @@ class ValOps {
   async initSources() {
     if (this.baseSha === null || this.sourcesSha === null || this.configSha === null || this.schemaSha === null || this.sources === null || this.schemas === null || this.modulesErrors === null) {
       const extracted = await extractValModules(this.valModules);
+      const moduleErrors = extracted.moduleErrors.concat(findNestedJsonValuesModuleErrors(extracted.schemas));
       this.sources = extracted.sources;
       this.schemas = extracted.schemas;
       this.baseSha = extracted.baseSha;
       this.schemaSha = extracted.schemaSha;
       this.sourcesSha = extracted.sourcesSha;
       this.configSha = extracted.configSha;
-      this.modulesErrors = extracted.moduleErrors;
+      this.modulesErrors = moduleErrors;
       return {
         baseSha: this.baseSha,
         schemaSha: this.schemaSha,
@@ -1325,7 +1968,7 @@ class ValOps {
         configSha: this.configSha,
         sources: extracted.sources,
         schemas: extracted.schemas,
-        moduleErrors: extracted.moduleErrors
+        moduleErrors
       };
     }
     return {
@@ -1348,6 +1991,221 @@ class ValOps {
   async getBaseSources() {
     return this.initSources().then(result => result.sources);
   }
+
+  /**
+   * Resolves the content of ONE `.jsonValues()` entry.
+   *
+   * The committed content comes from the entry's import thunk on the base
+   * source (so it works in both fs and http mode, with no extra I/O). With
+   * `applyPatches` (the default) any pending patches for that entry are then
+   * replayed on top, which is what makes draft edits visible to the runtime.
+   *
+   * Callers that apply patches themselves (the Studio, which owns
+   * in-flight client patches the server has not seen) must pass
+   * `applyPatches: false` or the same edits would be applied twice.
+   */
+  async getJsonEntry(moduleFilePath, entryKey, opts) {
+    const res = await this.getJsonEntries(moduleFilePath, {
+      keys: [entryKey]
+    }, opts);
+    if (res.status !== "success") {
+      return res;
+    }
+    const entry = res.entries[0];
+    if (entry !== undefined) {
+      return {
+        status: "success",
+        content: entry.content
+      };
+    }
+    const error = res.errors[0];
+    if (error !== undefined) {
+      return {
+        status: "error",
+        message: error.message
+      };
+    }
+    return {
+      status: "not-found",
+      message: `Entry not found: ${entryKey} in ${moduleFilePath}`
+    };
+  }
+
+  /**
+   * Resolves the content of MANY `.jsonValues()` entries in one pass.
+   *
+   * This is the single implementation; {@link getJsonEntry} is a one-key wrapper.
+   * Batching matters because the expensive parts — `initSources()` and
+   * `fetchPatches()` — are hoisted OUT of the per-entry loop: resolving 500
+   * entries one-by-one would otherwise mean 500 patch fetches.
+   *
+   * Per-entry problems stay per-entry (`missing` / `errors`) so one corrupt
+   * `*.val.json` cannot fail a whole batch. Only a missing or non-record MODULE
+   * is a whole-request `not-found`.
+   *
+   * `selector` is either explicit `keys` or an `offset`/`limit` window over every
+   * key of the record, in module key order. The window form requires
+   * `applyPatches: false`: enumerating from the base source would silently omit
+   * draft-added keys, and a silently-short key list is exactly the class of bug
+   * this endpoint exists to avoid.
+   */
+  async getJsonEntries(moduleFilePath, selector, opts) {
+    const applyPatches = (opts === null || opts === void 0 ? void 0 : opts.applyPatches) !== false;
+    const isWindow = !("keys" in selector);
+    if (isWindow && applyPatches) {
+      return {
+        status: "error",
+        message: "Cannot enumerate json entries by offset/limit with apply_patches: the base key set would omit draft-added entries. Pass apply_patches=false, or request explicit keys."
+      };
+    }
+    const {
+      sources,
+      schemas
+    } = await this.initSources();
+    const moduleSource = sources[moduleFilePath];
+    if (moduleSource === undefined || moduleSource === null) {
+      return {
+        status: "not-found",
+        message: `Module not found: ${moduleFilePath}`
+      };
+    }
+    if (typeof moduleSource !== "object" || Array.isArray(moduleSource)) {
+      return {
+        status: "not-found",
+        message: `Module is not a record: ${moduleFilePath}`
+      };
+    }
+    const record = moduleSource;
+    const allKeys = Object.keys(record);
+    const requestedKeys = isWindow ? allKeys.slice(selector.offset, selector.offset + selector.limit) : selector.keys;
+
+    // Fetched once for the whole batch, not per entry.
+    let modulePatches = [];
+    let serializedSchema = undefined;
+    if (applyPatches) {
+      const patchOps = await this.fetchPatches({
+        excludePatchOps: false
+      });
+      if (patchOps.error) {
+        return {
+          status: "error",
+          message: patchOps.error.message
+        };
+      }
+      if (patchOps.errors && Object.keys(patchOps.errors).length > 0) {
+        return {
+          status: "error",
+          message: `Could not fetch patches: ${JSON.stringify(patchOps.errors)}`
+        };
+      }
+      modulePatches = patchOps.patches.filter(p => p.path === moduleFilePath && !p.appliedAt).map(p => ({
+        patchId: p.patchId,
+        patch: p.patch
+      }));
+      try {
+        var _schemas$moduleFilePa;
+        serializedSchema = (_schemas$moduleFilePa = schemas[moduleFilePath]) === null || _schemas$moduleFilePa === void 0 ? void 0 : _schemas$moduleFilePa["executeSerialize"]();
+      } catch {
+        // Serialization errors are reported elsewhere; treat as "no schema".
+      }
+    }
+    const entries = [];
+    const missing = [];
+    const errors = [];
+    const resolved = await Promise.all(requestedKeys.map(async entryKey => {
+      const marker = record[entryKey];
+      if (marker !== undefined && !Internal.isJson(marker)) {
+        // Not a jsonValues entry — return the inlined value as-is (defensive).
+        // `inline` skips patch replay: entry patches are expressed against a
+        // jsonValues entry, and this value is part of the module source proper.
+        return {
+          entryKey,
+          baseContent: marker,
+          inline: true
+        };
+      }
+      if (marker === undefined) {
+        return {
+          entryKey,
+          baseContent: undefined
+        };
+      }
+      const thunk = Internal.getJsonImport(marker);
+      if (!thunk) {
+        return {
+          entryKey,
+          baseContent: null
+        };
+      }
+      try {
+        return {
+          entryKey,
+          baseContent: (await thunk()).default ?? null
+        };
+      } catch (e) {
+        return {
+          entryKey,
+          message: `Failed to load JSON entry '${entryKey}': ${e instanceof Error ? e.message : String(e)}`
+        };
+      }
+    }));
+    for (const result of resolved) {
+      const {
+        entryKey
+      } = result;
+      if ("message" in result) {
+        errors.push({
+          key: entryKey,
+          message: result.message
+        });
+        continue;
+      }
+      const {
+        baseContent
+      } = result;
+      if (!applyPatches || "inline" in result) {
+        if (baseContent === undefined) {
+          missing.push(entryKey);
+        } else {
+          entries.push({
+            key: entryKey,
+            content: baseContent
+          });
+        }
+        continue;
+      }
+      const res = applyJsonValuesEntryPatches({
+        serializedSchema,
+        entryKey,
+        baseContent,
+        patches: modulePatches
+      });
+      if (res.kind === "error") {
+        errors.push({
+          key: entryKey,
+          message: res.message
+        });
+      } else if (res.kind === "deleted") {
+        missing.push(entryKey);
+      } else {
+        entries.push({
+          key: entryKey,
+          content: res.content
+        });
+      }
+    }
+    return {
+      status: "success",
+      entries,
+      missing,
+      errors,
+      total: allKeys.length,
+      ...(isWindow ? {
+        offset: selector.offset,
+        limit: selector.limit
+      } : {})
+    };
+  }
   async getSchemas() {
     return this.initSources().then(result => result.schemas);
   }
@@ -1401,13 +2259,20 @@ class ValOps {
       // ops used to be applied twice. Idempotent for "replace", destructive for
       // array add/remove/move.
       if (hasSourceFileOps) {
+        var _patchesByModule$path;
         const path = patch.path;
         if (!patchesByModule[path]) {
           patchesByModule[path] = [];
         }
-        patchesByModule[path].push({
-          patchId: patch.patchId
-        });
+        // At most ONE entry per (module, patch): consumers treat each entry as
+        // "apply this whole patch". Pushing per-op made a patch with N non-file
+        // ops be applied N times — idempotent for `replace`, but it duplicates
+        // `add`s and corrupts non-idempotent ops like `move`.
+        if (((_patchesByModule$path = patchesByModule[path][patchesByModule[path].length - 1]) === null || _patchesByModule$path === void 0 ? void 0 : _patchesByModule$path.patchId) !== patch.patchId) {
+          patchesByModule[path].push({
+            patchId: patch.patchId
+          });
+        }
       }
     }
     return {
@@ -1417,6 +2282,15 @@ class ValOps {
   }
 
   // #region getRenders
+  /**
+   * Reifies each module's render from its schema INSTANCE.
+   *
+   * Kept even though the Studio also computes renders client-side: `select` is a
+   * user function that lives on the instance and is not part of the serialized
+   * schema, so a host app that does not render `<ValModulesClient>` has no
+   * instances in the browser and would otherwise get no renders at all. See
+   * #470.
+   */
   async getRenders(schemas, sources) {
     const renders = {};
     for (const [pathS, schema] of Object.entries(schemas)) {
@@ -1444,6 +2318,25 @@ class ValOps {
     } = await this.initSources();
     const patchedSources = {};
     const errors = {};
+    // Serialized schemas, resolved lazily and only for modules that actually
+    // have patches, so the common (non-jsonValues) case stays free.
+    const {
+      schemas
+    } = await this.initSources();
+    const serializedSchemaCache = new Map();
+    const jsonValuesSchemaFor = path => {
+      if (!serializedSchemaCache.has(path)) {
+        let serialized = undefined;
+        try {
+          var _schemas$path;
+          serialized = (_schemas$path = schemas[path]) === null || _schemas$path === void 0 ? void 0 : _schemas$path["executeSerialize"]();
+        } catch {
+          // Serialization errors are reported elsewhere; treat as "no schema".
+        }
+        serializedSchemaCache.set(path, serialized);
+      }
+      return serializedSchemaCache.get(path);
+    };
     for (const patchData of analysis.patches) {
       const path = patchData.path;
       if (sources[path] === undefined) {
@@ -1472,6 +2365,13 @@ class ValOps {
       } else {
         const applicableOps = [];
         const fileFixOps = {};
+        // `.jsonValues()` entry values are opaque `{_type:"json"}` markers in
+        // the module source — their content lives in the entry's `*.val.json`.
+        // Ops that reach INTO an entry therefore cannot be applied here (and
+        // would fail with "Cannot replace object element which does not exist",
+        // poisoning the rest of this module's patch chain). See the per-op
+        // routing below.
+        const serializedSchema = jsonValuesSchemaFor(path);
         for (const op of patchData.patch) {
           if (op.op === "file") {
             if (op.value !== null) {
@@ -1488,7 +2388,45 @@ class ValOps {
             // null value = delete: no patch_id to inject; the "remove" op in
             // the patch already removes the metadata entry from the source
           } else {
-            applicableOps.push(op);
+            const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+              kind: "normal"
+            };
+            if (cls.kind === "normal") {
+              applicableOps.push(op);
+            } else if (cls.subPath.length > 0) ; else if (op.op === "add" || op.op === "replace") {
+              // Whole-entry add/replace: keep the record's KEY SET correct for
+              // drafts by writing the marker rather than the content. Record
+              // validation only asserts `isJson`, and
+              // `validateJsonValuesEntries` skips thunkless markers by design.
+              applicableOps.push({
+                op: op.op,
+                path: op.path,
+                value: {
+                  [VAL_EXTENSION]: "json",
+                  patch_id: patchId
+                }
+              });
+            } else if (op.op === "remove") {
+              applicableOps.push(op);
+            } else {
+              // move/copy of a whole entry: the destination key must appear, and
+              // for a move the source key must disappear. Both are key-set
+              // changes we can express with markers.
+              applicableOps.push({
+                op: "add",
+                path: op.path,
+                value: {
+                  [VAL_EXTENSION]: "json",
+                  patch_id: patchId
+                }
+              });
+              if (op.op === "move" && array.isNonEmpty(op.from)) {
+                applicableOps.push({
+                  op: "remove",
+                  path: op.from
+                });
+              }
+            }
           }
         }
         const patchRes = applyPatch(deepClone(patchedSources[path]),
@@ -1595,6 +2533,21 @@ class ValOps {
         continue;
       }
       const res = schema["executeValidate"](path, source);
+      // For `.jsonValues()` records, executeValidate only checks the entry
+      // markers; load + validate each entry's backing `*.val.json` content here.
+      const jsonValuesErrors = await validateJsonValuesEntries(schema, source, path);
+      for (const [sourcePathS, entryErrors] of Object.entries(jsonValuesErrors)) {
+        const sourcePath = sourcePathS;
+        if (!errors[path]) {
+          errors[path] = {
+            validations: {}
+          };
+        }
+        if (!errors[path].validations[sourcePath]) {
+          errors[path].validations[sourcePath] = [];
+        }
+        errors[path].validations[sourcePath].push(...entryErrors);
+      }
       if (res === false) {
         continue;
       }
@@ -1837,6 +2790,10 @@ class ValOps {
     const previousSourceFiles = {};
     const partiallyPatchedSourceFiles = {};
     const unappliablePatches = {};
+
+    // Serialized schemas are needed to route ops that target `.jsonValues()`
+    // entries (their content lives in `*.val.json`, not the `.val.ts`).
+    const schemas = await this.getSchemas();
     const applySourceFilePatches = async (path, patches) => {
       const sourceFileRes = await this.getSourceFile(path);
       const errors = [];
@@ -1847,13 +2804,99 @@ class ValOps {
         });
         return {
           path,
-          errors,
-          skippedPatches: patches.map(p => p.patchId)
-        };
-      }
-      const sourceFile = sourceFileRes.data;
-      previousSourceFiles[path] = sourceFile;
-      let tsSourceFile = ts.createSourceFile("<val>", sourceFile, ts.ScriptTarget.ES2015);
+          errors,
+          skippedPatches: patches.map(p => p.patchId)
+        };
+      }
+      const sourceFile = sourceFileRes.data;
+      previousSourceFiles[path] = sourceFile;
+      const originalSourceFile = ts.createSourceFile("<val>", sourceFile, ts.ScriptTarget.ES2015);
+      let tsSourceFile = originalSourceFile;
+      let tsChanged = false;
+      let serializedSchema = undefined;
+      try {
+        var _schemas$path2;
+        serializedSchema = (_schemas$path2 = schemas[path]) === null || _schemas$path2 === void 0 ? void 0 : _schemas$path2["executeSerialize"]();
+      } catch {
+        // Serialization errors are reported elsewhere; treat as "no schema".
+        // Without this guard one unserializable schema (e.g. a `keyOf` with an
+        // empty selector) rejects the whole prepare(), so NO module's patches
+        // can be saved — instead of this module's ops being routed as plain
+        // `.val.ts` ops and any that cannot apply reported per-patch.
+      }
+
+      // jsonValues entry content, keyed by `*.val.json` path. `null` = delete.
+      const jsonEntryContents = new Map();
+      // Entries added in this commit → their new `*.val.json` path, so later
+      // content ops in the same commit resolve to the freshly-created file.
+      const entryKeyToJsonPath = new Map();
+
+      // Lazily analyzed `c.json(() => import("..."))` entries of the ORIGINAL
+      // `.val.ts` (import paths are authoritative for existing/hand-placed files).
+      let analyzerEntries = null;
+      const resolveEntryJsonPath = entryKey => {
+        const added = entryKeyToJsonPath.get(entryKey);
+        if (added !== undefined) {
+          return result.ok(added);
+        }
+        if (analyzerEntries === null) {
+          const analysis = analyzeValModule(originalSourceFile);
+          if (result.isErr(analysis)) {
+            return result.err(analysis.error);
+          }
+          analyzerEntries = analyzeJsonValuesEntries(analysis.value.source);
+        }
+        const entry = analyzerEntries.get(entryKey);
+        if (!entry) {
+          return result.err({
+            message: `Could not find jsonValues entry '${entryKey}' in ${path}`,
+            filePath: path
+          });
+        }
+        return result.ok(resolveExistingJsonPath(path, entry.importPath));
+      };
+      const loadEntryContent = async jsonPath => {
+        const current = jsonEntryContents.get(jsonPath);
+        if (current !== undefined) {
+          if (current === null) {
+            return result.err({
+              message: `Cannot edit a removed jsonValues entry: ${jsonPath}`,
+              filePath: jsonPath
+            });
+          }
+          return result.ok(current);
+        }
+        const res = await this.getSourceFile(jsonPath);
+        if (res.error) {
+          return result.err({
+            message: res.error.message,
+            filePath: jsonPath
+          });
+        }
+        try {
+          const parsed = JSON.parse(res.data);
+          jsonEntryContents.set(jsonPath, parsed);
+          return result.ok(parsed);
+        } catch (err) {
+          return result.err({
+            message: `Could not parse jsonValues entry ${jsonPath}: ${err instanceof Error ? err.message : String(err)}`,
+            filePath: jsonPath
+          });
+        }
+      };
+      const collectPatchError = (err, patchId, op) => {
+        console.error("Could not patch", JSON.stringify({
+          path,
+          patchId,
+          error: err,
+          op
+        }, null, 2));
+        if (Array.isArray(err)) {
+          errors.push(...err);
+        } else {
+          errors.push(err);
+        }
+      };
       const appliedPatches = [];
       const triedPatches = [];
       for (const {
@@ -1877,43 +2920,232 @@ class ValOps {
         }
         const patch = patchData.patch;
         const sourceFileOps = patch.filter(op => op.op !== "file"); // file is not a valid source file op
-        const patchRes = applyPatch(tsSourceFile, tsOps, sourceFileOps);
-        if (result.isErr(patchRes)) {
-          if (Array.isArray(patchRes.error)) {
-            for (const error of patchRes.error) {
-              console.error("Could not patch", JSON.stringify({
-                path,
-                patchId,
-                error,
-                sourceFileOps
-              }, null, 2));
-            }
-            errors.push(...patchRes.error);
+        let patchHadError = false;
+        // Where this patch's errors start, so the unappliable-patch report below
+        // can name what went wrong rather than just that something did.
+        const errorsBefore = errors.length;
+        for (const op of sourceFileOps) {
+          const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+            kind: "normal"
+          };
+          // `move` / `copy` also READ from a path: classify that too, so an op
+          // that moves a value out of (or into) a jsonValues entry cannot slip
+          // through as a plain `.val.ts` op.
+          const fromCls = serializedSchema && (op.op === "move" || op.op === "copy") ? classifyJsonValuesOp(serializedSchema, op.from) : {
+            kind: "normal"
+          };
+          if (cls.kind === "normal" && fromCls.kind === "normal") {
+            const patchRes = applyPatch(tsSourceFile, tsOps, [op]);
+            if (result.isErr(patchRes)) {
+              collectPatchError(patchRes.error, patchId, op);
+              patchHadError = true;
+              break;
+            }
+            tsSourceFile = patchRes.value;
+            tsChanged = true;
+            continue;
+          }
+          if (cls.kind === "normal") {
+            errors.push({
+              message: `Cannot '${op.op}' a value out of a jsonValues entry and into the module source`,
+              filePath: path
+            });
+            patchHadError = true;
+            break;
+          }
+          // Nested `.jsonValues()` records are not supported: only the read path
+          // for a module's ROOT record/router is implemented end to end. This is
+          // also rejected up front in `initSources`; this is defense in depth.
+          if (cls.recordPath.length > 0 || fromCls.kind === "entry" && fromCls.recordPath.length > 0) {
+            errors.push({
+              message: `Nested .jsonValues() records are not supported: '${cls.recordPath.join(".")}' in ${path}. Use .jsonValues() only on a module's root record/router.`,
+              filePath: path
+            });
+            patchHadError = true;
+            break;
+          }
+          // The op targets a `.jsonValues()` entry.
+          if (cls.subPath.length === 0) {
+            // Structural / whole-entry op.
+            if (op.op === "add") {
+              const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
+              if (result.isErr(newPathsRes)) {
+                errors.push(newPathsRes.error);
+                patchHadError = true;
+                break;
+              }
+              const {
+                jsonPath,
+                importPath
+              } = newPathsRes.value;
+              const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
+              if (result.isErr(insRes)) {
+                collectPatchError(insRes.error, patchId, op);
+                patchHadError = true;
+                break;
+              }
+              tsSourceFile = insRes.value;
+              tsChanged = true;
+              jsonEntryContents.set(jsonPath, op.value);
+              entryKeyToJsonPath.set(cls.entryKey, jsonPath);
+            } else if (op.op === "remove") {
+              const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+              if (result.isErr(jsonPathRes)) {
+                errors.push(jsonPathRes.error);
+                patchHadError = true;
+                break;
+              }
+              const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey);
+              if (result.isErr(remRes)) {
+                collectPatchError(remRes.error, patchId, op);
+                patchHadError = true;
+                break;
+              }
+              tsSourceFile = remRes.value;
+              tsChanged = true;
+              jsonEntryContents.set(jsonPathRes.value, null);
+            } else if (op.op === "replace") {
+              const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+              if (result.isErr(jsonPathRes)) {
+                errors.push(jsonPathRes.error);
+                patchHadError = true;
+                break;
+              }
+              jsonEntryContents.set(jsonPathRes.value, op.value);
+            } else if (op.op === "move" || op.op === "copy") {
+              // Rename (move) or duplicate (copy) a whole entry. The new entry
+              // gets its own `*.val.json` written with the source entry's
+              // content plus a `c.json(...)` thunk; a move additionally drops
+              // the old thunk and deletes the old file.
+              if (fromCls.kind !== "entry" || fromCls.subPath.length !== 0 || fromCls.recordPath.join("\0") !== cls.recordPath.join("\0")) {
+                errors.push({
+                  message: `Cannot '${op.op}' a jsonValues entry across records or from a non-entry path (from '${op.from.join(".")}' to '${op.path.join(".")}')`,
+                  filePath: path
+                });
+                patchHadError = true;
+                break;
+              }
+              const fromKey = fromCls.entryKey;
+              const fromPathRes = resolveEntryJsonPath(fromKey);
+              if (result.isErr(fromPathRes)) {
+                errors.push(fromPathRes.error);
+                patchHadError = true;
+                break;
+              }
+              // Load BEFORE marking anything deleted: `loadEntryContent` errors
+              // on a path that has already been nulled in this commit.
+              const contentRes = await loadEntryContent(fromPathRes.value);
+              if (result.isErr(contentRes)) {
+                errors.push(contentRes.error);
+                patchHadError = true;
+                break;
+              }
+              const content = deepClone(contentRes.value);
+              if (op.op === "move") {
+                const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, fromKey);
+                if (result.isErr(remRes)) {
+                  collectPatchError(remRes.error, patchId, op);
+                  patchHadError = true;
+                  break;
+                }
+                tsSourceFile = remRes.value;
+              }
+              // LOCKED convention: the destination always uses the generated
+              // path, so renaming a hand-placed file relocates it.
+              const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
+              if (result.isErr(newPathsRes)) {
+                errors.push(newPathsRes.error);
+                patchHadError = true;
+                break;
+              }
+              const {
+                jsonPath,
+                importPath
+              } = newPathsRes.value;
+              const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
+              if (result.isErr(insRes)) {
+                collectPatchError(insRes.error, patchId, op);
+                patchHadError = true;
+                break;
+              }
+              tsSourceFile = insRes.value;
+              tsChanged = true;
+              jsonEntryContents.set(jsonPath, content);
+              entryKeyToJsonPath.set(cls.entryKey, jsonPath);
+              if (op.op === "move" && fromPathRes.value !== jsonPath) {
+                jsonEntryContents.set(fromPathRes.value, null);
+              }
+            } else {
+              errors.push({
+                message: `Unsupported op '${op.op}' on jsonValues entry '${cls.entryKey}' (supported: add, remove, replace, move, copy)`,
+                filePath: path
+              });
+              patchHadError = true;
+              break;
+            }
           } else {
-            console.error("Could not patch", JSON.stringify({
-              path,
-              patchId,
-              error: patchRes.error,
-              sourceFileOps
-            }, null, 2));
-            errors.push(patchRes.error);
+            // Content sub-op: replay against the entry's `*.val.json`.
+            // `rebaseContentOp` slices `from` by the same prefix as `path`, so a
+            // cross-entry move/copy would silently corrupt the target entry.
+            if ((op.op === "move" || op.op === "copy") && (fromCls.kind !== "entry" || fromCls.entryKey !== cls.entryKey)) {
+              errors.push({
+                message: `Cannot '${op.op}' between different jsonValues entries`,
+                filePath: path
+              });
+              patchHadError = true;
+              break;
+            }
+            const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+            if (result.isErr(jsonPathRes)) {
+              errors.push(jsonPathRes.error);
+              patchHadError = true;
+              break;
+            }
+            const jsonPath = jsonPathRes.value;
+            const contentRes = await loadEntryContent(jsonPath);
+            if (result.isErr(contentRes)) {
+              errors.push(contentRes.error);
+              patchHadError = true;
+              break;
+            }
+            const rebasedRes = rebaseContentOp(op, cls.recordPath.length + 1);
+            if (result.isErr(rebasedRes)) {
+              errors.push({
+                message: rebasedRes.error.message,
+                filePath: jsonPath
+              });
+              patchHadError = true;
+              break;
+            }
+            const applied = applyPatch(deepClone(contentRes.value), jsonOps, [rebasedRes.value]);
+            if (result.isErr(applied)) {
+              collectPatchError(applied.error, patchId, op);
+              patchHadError = true;
+              break;
+            }
+            jsonEntryContents.set(jsonPath, applied.value);
           }
+        }
+        if (patchHadError) {
           unappliablePatches[patchId] = {
             moduleFilePath: path,
-            message: formatPatchSourceError(patchRes.error)
+            // The per-op loop reports through `errors`, so take what it added
+            // for THIS patch — the same information a single applyPatch gives
+            // via formatPatchSourceError.
+            message: errors.slice(errorsBefore).map(formatPatchSourceError).join("\n") || `Could not apply patch: ${patchId}`
           };
           triedPatches.push(patchId);
           if (continueOnError) {
-            // Continue from the unchanged source file: the failing patch made
-            // no change, so the rest of the chain applies on top of the state
-            // it had before it. This mirrors what the client already does in
-            // ValSyncEngine.getPatchedSource.
+            // Carry on so a single run reports EVERY unappliable patch, not just
+            // the first per module. Note that the ops of this patch BEFORE the
+            // failing one have already been applied, so what follows builds on a
+            // partially patched state — fine, because continueOnError is
+            // diagnosis only and the commit is refused regardless.
             continue;
           }
           break;
         }
         appliedPatches.push(patchId);
-        tsSourceFile = patchRes.value;
       }
       if (errors.length > 0 && continueOnError) {
         // Diagnosis: expose what the source file would look like with the
@@ -1922,33 +3154,58 @@ class ValOps {
         partiallyPatchedSourceFiles[path] = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
       }
       if (errors.length === 0) {
-        var _this$options;
         // https://github.com/microsoft/TypeScript/issues/36174
-        let sourceFileText = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
-        if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.formatter) {
-          try {
-            sourceFileText = await this.options.formatter(sourceFileText, path);
-          } catch (err) {
-            errors.push({
-              message: "Could not format source file: " + (err instanceof Error ? err.message : "Unknown error")
-            });
+        let sourceFileText = null;
+        if (tsChanged) {
+          var _this$options;
+          sourceFileText = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
+          if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.formatter) {
+            try {
+              sourceFileText = await this.options.formatter(sourceFileText, path);
+            } catch (err) {
+              errors.push({
+                message: "Could not format source file: " + (err instanceof Error ? err.message : "Unknown error")
+              });
+            }
           }
         }
-        return {
-          path,
-          appliedPatches,
-          result: sourceFileText
-        };
-      } else {
-        const skippedPatches = patches.slice(appliedPatches.length + triedPatches.length).map(p => p.patchId);
-        return {
-          path,
-          appliedPatches,
-          triedPatches,
-          skippedPatches,
-          errors
-        };
+        const extraFiles = {};
+        for (const [jsonPath, content] of Array.from(jsonEntryContents)) {
+          var _this$options2;
+          if (content === null) {
+            extraFiles[jsonPath] = null;
+            continue;
+          }
+          let jsonText = JSON.stringify(content, null, 2);
+          if ((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.formatter) {
+            try {
+              jsonText = await this.options.formatter(jsonText, jsonPath);
+            } catch (err) {
+              errors.push({
+                message: "Could not format jsonValues entry: " + (err instanceof Error ? err.message : "Unknown error"),
+                filePath: jsonPath
+              });
+            }
+          }
+          extraFiles[jsonPath] = jsonText;
+        }
+        if (errors.length === 0) {
+          return {
+            path,
+            appliedPatches,
+            result: sourceFileText,
+            extraFiles
+          };
+        }
       }
+      const skippedPatches = patches.slice(appliedPatches.length + triedPatches.length).map(p => p.patchId);
+      return {
+        path,
+        appliedPatches,
+        triedPatches,
+        skippedPatches,
+        errors
+      };
     };
     const allResults = await Promise.all(Object.entries(patchesByModule).map(([path, patches]) => applySourceFilePatches(path, patches)));
     let hasErrors = false;
@@ -1967,7 +3224,14 @@ class ValOps {
         triedPatches[res.path] = res.triedPatches ?? [];
         skippedPatches[res.path] = res.skippedPatches ?? [];
       } else {
-        patchedSourceFiles[res.path] = res.result;
+        // `result` is null when the `.val.ts` itself was not changed (pure
+        // jsonValues content edits only write `*.val.json` extraFiles).
+        if (res.result !== null) {
+          patchedSourceFiles[res.path] = res.result;
+        }
+        for (const [extraPath, data] of Object.entries(res.extraFiles)) {
+          patchedSourceFiles[extraPath] = data;
+        }
         appliedPatches[res.path] = res.appliedPatches ?? [];
       }
       for (const patchId of res.appliedPatches ?? []) {
@@ -2144,6 +3408,130 @@ function bufferFromDataUrl(dataUrl) {
   }
 }
 
+/**
+ * The `*.val.json` files backing a `.jsonValues()` module's entries, as paths
+ * relative to the project root.
+ *
+ * Read out of the `.val.ts` rather than off the loaded module: the entry's path
+ * only exists as the string literal inside its `c.json(() => import("..."))`
+ * thunk, and the loaded marker does not carry it.
+ */
+function findJsonEntryFilePathsInSource(moduleFilePath, valTsSourceFile) {
+  let analysis;
+  try {
+    analysis = analyzeValModule(valTsSourceFile);
+  } catch {
+    return [];
+  }
+  if (result.isErr(analysis)) {
+    return [];
+  }
+  const paths = [];
+  analyzeJsonValuesEntries(analysis.value.source).forEach(entry => {
+    paths.push(resolveExistingJsonPath(moduleFilePath, entry.importPath));
+  });
+  return paths;
+}
+
+/**
+ * A fingerprint of every `.jsonValues()` entry file on disk, for change
+ * detection.
+ *
+ * Uses each file's SIZE + MTIME, never its content: reading every entry on every
+ * stat would undo the point of `.jsonValues()`, and the question here is only
+ * "did any of them change", not "what do they say now".
+ *
+ * Why this needs to exist at all: `sourcesSha` and `baseSha` are computed from
+ * `JSON.stringify(source)`, and a jsonValues module's source is just markers —
+ * the content is behind a thunk, which `JSON.stringify` drops. So no existing sha
+ * can see an entry edit, and the Studio has no way to learn that a hand-edited
+ * `*.val.json` changed.
+ *
+ * Deliberately NOT folded into `sourcesSha`: that is computed by the client too
+ * (from the ValModules registry, which has no entry content), so the two would
+ * disagree and trip the schema-out-of-date machinery.
+ */
+class JsonEntryFilesFingerprint {
+  /** Entry paths per module, memoized on the `.val.ts` mtime that produced them. */
+  cache = new Map();
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  compute(schemas) {
+    const parts = [];
+    for (const entryFilePath of this.entryFilePaths(schemas)) {
+      parts.push(`${entryFilePath}:${this.fileFingerprint(entryFilePath)}`);
+    }
+    return parts.join("|");
+  }
+
+  /**
+   * Every `.jsonValues()` entry file the given schemas reach, rootDir-relative and
+   * in a stable order.
+   *
+   * Public because the fingerprint is only half the story: the fs polling fallback
+   * (which exists because `fs.watch` is unreliable on some systems, notably WSL)
+   * has to watch these files too, or on those systems a hand-edited entry waits
+   * out the whole long-poll interval.
+   */
+  entryFilePaths(schemas) {
+    const paths = [];
+    for (const moduleFilePathS of Object.keys(schemas).sort()) {
+      const moduleFilePath = moduleFilePathS;
+      const schema = schemas[moduleFilePath];
+      // Root-only, per locked decision #7 — so a module whose root is not a
+      // jsonValues record has no entry files to fingerprint.
+      if (schema === undefined || schema.type !== "record" || schema.jsonValues !== true) {
+        continue;
+      }
+      paths.push(...this.entryFilePathsOf(moduleFilePath));
+    }
+    return paths;
+  }
+  entryFilePathsOf(moduleFilePath) {
+    const absModulePath = path__default.join(this.rootDir, moduleFilePath);
+    let moduleMtimeMs;
+    try {
+      moduleMtimeMs = fs.statSync(absModulePath).mtimeMs;
+    } catch {
+      return [];
+    }
+    const cached = this.cache.get(moduleFilePath);
+    // The entry LIST only changes when the `.val.ts` does (that is where the
+    // thunks live), so parsing it again on every stat would be wasted work.
+    if (cached && cached.moduleMtimeMs === moduleMtimeMs) {
+      return cached.entryFilePaths;
+    }
+    let entryFilePaths = [];
+    try {
+      const contents = fs.readFileSync(absModulePath, "utf-8");
+      entryFilePaths = findJsonEntryFilePathsInSource(moduleFilePath, ts.createSourceFile(absModulePath, contents, ts.ScriptTarget.ES2015));
+    } catch {
+      entryFilePaths = [];
+    }
+    this.cache.set(moduleFilePath, {
+      moduleMtimeMs,
+      entryFilePaths
+    });
+    return entryFilePaths;
+  }
+  fileFingerprint(entryFilePath) {
+    try {
+      // NANOSECOND mtime, not `mtimeMs`: two writes inside the same millisecond
+      // that happen to preserve the file size would otherwise be indistinguishable
+      // from no change at all, and the edit would silently never reach the Studio.
+      const stat = fs.statSync(path__default.join(this.rootDir, entryFilePath), {
+        bigint: true
+      });
+      return `${stat.size}:${stat.mtimeNs}`;
+    } catch {
+      // Missing is a state too — going from present to absent must change the
+      // fingerprint, not be indistinguishable from unchanged.
+      return "missing";
+    }
+  }
+}
+
 /**
  * Computes the changed patch parent references based on the current patches and the patch IDs to be deleted.
  *
@@ -2235,6 +3623,14 @@ function getFileExt(filePath) {
   return filePath.split(".").pop() || "";
 }
 
+/** Serializes a schema, or gives up quietly — serialization errors are reported elsewhere. */
+function serializeSchemaSafely(schema) {
+  try {
+    return schema === null || schema === void 0 ? void 0 : schema["executeSerialize"]();
+  } catch {
+    return undefined;
+  }
+}
 class ValOpsFS extends ValOps {
   static VAL_DIR = ".val";
   constructor(contentUrl, rootDir, valModules, options) {
@@ -2242,7 +3638,14 @@ class ValOpsFS extends ValOps {
     this.contentUrl = contentUrl;
     this.rootDir = rootDir;
     this.host = new FSOpsHost();
+    this.jsonEntryFilesFingerprint = new JsonEntryFilesFingerprint(rootDir);
   }
+
+  /**
+   * Change detection for `.jsonValues()` entry files, which no sha can see (their
+   * content lives behind a thunk that `JSON.stringify` drops).
+   */
+
   async onInit() {
     // do nothing
   }
@@ -2331,7 +3734,11 @@ class ValOpsFS extends ValOps {
       const currentBaseSha = await this.getBaseSha();
       const currentSchemaSha = await this.getSchemaSha();
       const currentSourcesSha = await this.getSourcesSha();
-      const moduleFilePaths = Object.keys(await this.getSchemas());
+      const schemas = await this.getSchemas();
+      const moduleFilePaths = Object.keys(schemas);
+      const serializedSchemas = Object.fromEntries(Object.entries(schemas).map(([path, schema]) => [path, serializeSchemaSafely(schema)]));
+      const currentJsonEntriesSha = this.jsonEntryFilesFingerprint.compute(serializedSchemas);
+      const jsonEntryFilePaths = this.jsonEntryFilesFingerprint.entryFilePaths(serializedSchemas);
       const patchData = await this.readPatches();
       const patches = [];
       // TODO: use proper patch sequences when available:
@@ -2341,7 +3748,10 @@ class ValOpsFS extends ValOps {
         patches.push(patchId);
       }
       // something changed: return immediately
-      const didChange = !params || currentBaseSha !== params.baseSha ||
+      const didChange = !params ||
+      // An entry file changed on disk: nothing else here can see that, since a
+      // jsonValues module's source is markers.
+      params.jsonEntriesSha !== undefined && currentJsonEntriesSha !== params.jsonEntriesSha || currentBaseSha !== params.baseSha ||
       // base sha covers both sources sha and schema sha, so we could remove checks for schema sha and sources sha
       currentSourcesSha !== params.sourcesSha || currentSchemaSha !== params.schemaSha || patches.length !== params.patches.length || patches.some((p, i) => p !== params.patches[i]);
       if (didChange) {
@@ -2350,7 +3760,8 @@ class ValOpsFS extends ValOps {
           baseSha: currentBaseSha,
           schemaSha: currentSchemaSha,
           sourcesSha: currentSourcesSha,
-          patches
+          patches,
+          jsonEntriesSha: currentJsonEntriesSha
         };
       }
       let fsWatcher = null;
@@ -2433,7 +3844,12 @@ class ValOpsFS extends ValOps {
         patchesDirHandle = handle;
       }),
       // we poll the files that Val depends on for changes
-      disableFilePolling ? new Promise(() => {}) : didFilesChangeUsingPolling([path__default.join(this.rootDir, "val.config.ts"), path__default.join(this.rootDir, "val.modules.ts"), path__default.join(this.rootDir, "val.config.js"), path__default.join(this.rootDir, "val.modules.js"), ...moduleFilePaths.map(p => path__default.join(this.rootDir, p))], statFilePollingInterval, handle => {
+      disableFilePolling ? new Promise(() => {}) : didFilesChangeUsingPolling([path__default.join(this.rootDir, "val.config.ts"), path__default.join(this.rootDir, "val.modules.ts"), path__default.join(this.rootDir, "val.config.js"), path__default.join(this.rootDir, "val.modules.js"), ...moduleFilePaths.map(p => path__default.join(this.rootDir, p)),
+      // The `.jsonValues()` entry files too: their content is invisible
+      // to every sha, and this polling fallback exists for the systems
+      // where the `fs.watch` below does not fire (notably WSL) — without
+      // them a hand-edited entry waits out the whole long-poll interval.
+      ...jsonEntryFilePaths.map(p => path__default.join(this.rootDir, p))], statFilePollingInterval, handle => {
         valFilesIntervalHandle = handle;
       }), new Promise(resolve => {
         fsWatcher = fs.watch(this.rootDir, {
@@ -2442,7 +3858,11 @@ class ValOpsFS extends ValOps {
           if (!filename) {
             return;
           }
-          const isChange = filename.startsWith(this.getPatchesDir().slice(this.rootDir.length + 1)) || filename.endsWith(".val.ts") || filename.endsWith(".val.js") || filename.endsWith("val.config.ts") || filename.endsWith("val.config.js") || filename.endsWith("val.modules.ts") || filename.endsWith("val.modules.js");
+          const isChange = filename.startsWith(this.getPatchesDir().slice(this.rootDir.length + 1)) || filename.endsWith(".val.ts") || filename.endsWith(".val.js") ||
+          // A `.jsonValues()` entry file. Its content is invisible to every
+          // sha (see JsonEntryFilesFingerprint), so without this a
+          // hand-edited entry never reaches an open Studio.
+          filename.endsWith(".val.json") || filename.endsWith("val.config.ts") || filename.endsWith("val.config.js") || filename.endsWith("val.modules.ts") || filename.endsWith("val.modules.js");
           if (isChange) {
             // a file that Val depends on just changed or a patch was created, break connection and request stat again to get the new values
             resolve("request-again");
@@ -2464,7 +3884,8 @@ class ValOpsFS extends ValOps {
         baseSha: currentBaseSha,
         schemaSha: currentSchemaSha,
         sourcesSha: currentSourcesSha,
-        patches
+        patches,
+        jsonEntriesSha: currentJsonEntriesSha
       };
     } catch (err) {
       if (err instanceof Error) {
@@ -4405,7 +5826,7 @@ function hasRemoteFileSchema(schema) {
       }
     }
     return false;
-  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "keyOf" || schema.type === "route") {
+  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "keyOf" || schema.type === "route") {
     return false;
   } else {
     const exhaustiveCheck = schema;
@@ -5523,6 +6944,144 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    // #region json
+    // Loads the content of a single `.jsonValues()` entry by key, so the Studio
+    // can lazily load just the entry being opened, and the runtime can read draft
+    // edits. With apply_patches (default true) pending patches for the entry are
+    // replayed server-side; the Studio passes false and overlays its own.
+    "/json": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        if (serverOps instanceof ValOpsHttp && !("id" in auth)) {
+          return {
+            status: 401,
+            json: {
+              message: "Unauthorized"
+            }
+          };
+        }
+        const moduleFilePath = req.query.path;
+        const {
+          key,
+          keys,
+          offset,
+          limit
+        } = req.query;
+        // Defaults to true, mirroring /sources/~. The Studio opts out.
+        const applyPatches = req.query.apply_patches !== false;
+        const isWindow = offset !== undefined || limit !== undefined;
+        const shapes = [key !== undefined, keys !== undefined, isWindow].filter(Boolean).length;
+        if (shapes !== 1) {
+          return {
+            status: 400,
+            json: {
+              message: "Exactly one of 'key', 'keys' or 'offset'+'limit' must be given"
+            }
+          };
+        }
+        if (isWindow && (offset === undefined || limit === undefined)) {
+          return {
+            status: 400,
+            json: {
+              message: "'offset' and 'limit' must be given together"
+            }
+          };
+        }
+        if (key !== undefined) {
+          const res = await serverOps.getJsonEntry(moduleFilePath, key, {
+            applyPatches
+          });
+          if (res.status === "unauthorized") {
+            return {
+              status: 401,
+              json: {
+                message: res.message
+              }
+            };
+          }
+          if (res.status === "not-found") {
+            return {
+              status: 404,
+              json: {
+                message: res.message
+              }
+            };
+          }
+          if (res.status === "error") {
+            return {
+              status: 500,
+              json: {
+                message: res.message
+              }
+            };
+          }
+          return {
+            status: 200,
+            json: {
+              path: moduleFilePath,
+              key,
+              content: res.content
+            }
+          };
+        }
+        const res = await serverOps.getJsonEntries(moduleFilePath, keys !== undefined ? {
+          keys
+        } : {
+          offset: offset,
+          limit: limit
+        }, {
+          applyPatches
+        });
+        if (res.status === "unauthorized") {
+          return {
+            status: 401,
+            json: {
+              message: res.message
+            }
+          };
+        }
+        if (res.status === "not-found") {
+          return {
+            status: 404,
+            json: {
+              message: res.message
+            }
+          };
+        }
+        if (res.status === "error") {
+          return {
+            status: 500,
+            json: {
+              message: res.message
+            }
+          };
+        }
+        return {
+          status: 200,
+          json: {
+            path: moduleFilePath,
+            entries: res.entries,
+            missing: res.missing,
+            errors: res.errors,
+            ...(res.offset !== undefined ? {
+              offset: res.offset
+            } : {}),
+            ...(res.limit !== undefined ? {
+              limit: res.limit
+            } : {}),
+            total: res.total
+          }
+        };
+      }
+    },
     // #region sources
     "/sources/~": {
       PUT: async req => {
@@ -8704,6 +10263,23 @@ function createModulePathMap(sourceFile) {
     }
   }
 }
+
+/**
+ * The {@link createModulePathMap} equivalent for a `.jsonValues()` entry's
+ * backing `*.val.json`.
+ *
+ * The file IS the entry's value, so the map is rooted at the JSON document
+ * rather than at a `c.define` argument — but everything below is the same shape,
+ * which means a module path like `"title"` (the part after the entry key)
+ * resolves against it exactly as it would inside a `.val.ts`.
+ */
+function createJsonEntryPathMap(jsonSourceFile) {
+  const statement = jsonSourceFile.statements[0];
+  if (!statement) {
+    return undefined;
+  }
+  return traverse(statement.expression, jsonSourceFile);
+}
 function traverse(node, sourceFile) {
   if (ts.isStringLiteral(node) || ts.isNumericLiteral(node)) {
     return {
@@ -8793,6 +10369,93 @@ function traverseObjectLiteral(node, sourceFile) {
   }, {});
 }
 
+/**
+ * Which `*.val.json` holds a `.jsonValues()` entry's content, given the module's
+ * `.val.ts`.
+ *
+ * Tooling that maps a validation `sourcePath` back to a place in a file needs
+ * this: for a jsonValues module the offending value is NOT in the `.val.ts` at
+ * all — that file only holds `c.json(() => import("./x.val.json"))` — so a
+ * resolver that only ever looks at the `.val.ts` can report the error but not
+ * where it lives, which for a record with hundreds of entries is not much of a
+ * report.
+ *
+ * Returns a path relative to the project root (leading slash), or undefined when
+ * the module has no such entry (not a jsonValues module, unparseable, or the key
+ * is not backed by a `c.json` thunk).
+ */
+function findJsonEntryFilePath(moduleFilePath, valTsSourceFile, entryKey) {
+  let analysis;
+  try {
+    analysis = analyzeValModule(valTsSourceFile);
+  } catch {
+    return undefined;
+  }
+  if (result.isErr(analysis)) {
+    return undefined;
+  }
+  const entry = analyzeJsonValuesEntries(analysis.value.source).get(entryKey);
+  if (!entry) {
+    return undefined;
+  }
+  return resolveExistingJsonPath(moduleFilePath, entry.importPath);
+}
+
+/**
+ * Moves ONE `.jsonValues()` entry that was written inline in the `.val.ts` into
+ * its own `*.val.json`, replacing the inline value with
+ * `c.json(() => import("./<key>.val.json"))`.
+ *
+ * This is the fix for the `jsonValues:extract-entry` validation error. It is not
+ * expressible as a patch (a patch edits one `.val.ts` and cannot create the
+ * backing JSON file), so it writes both files directly — JSON first, so a
+ * failure part-way through never leaves the module pointing at a file that does
+ * not exist.
+ *
+ * Root-only, like the rest of the `.jsonValues()` machinery: the entry is looked
+ * up in the module's root record/router object literal.
+ */
+function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sourceFileHandler) {
+  const valTsPath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${moduleFilePath.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
+  const sourceFile = sourceFileHandler.getSourceFile(valTsPath);
+  if (!sourceFile) {
+    throw Error(`Source file ${valTsPath} not found`);
+  }
+  const pathsRes = getNewJsonEntryPaths(moduleFilePath, entryKey);
+  if (result.isErr(pathsRes)) {
+    throw Error(formatPatchSourceError(pathsRes.error));
+  }
+  const {
+    jsonPath,
+    importPath
+  } = pathsRes.value;
+  const absoluteJsonPath = path__default.join(rootDir, jsonPath);
+  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
+    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
+  }
+
+  // Remove the inline property, then add the `c.json(...)` reference back. The
+  // entry moves to the end of the record: entry ORDER in a jsonValues record is
+  // not meaningful (the Studio and the runtime key entries by name), and
+  // insert-in-place would mean reimplementing insertValJsonEntry.
+  const removed = removeValJsonEntry(sourceFile, [], entryKey);
+  if (result.isErr(removed)) {
+    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+  }
+  const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
+  if (result.isErr(inserted)) {
+    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+  }
+  sourceFileHandler.writeFile(absoluteJsonPath, JSON.stringify(content, null, 2) + "\n", "utf8");
+  sourceFileHandler.writeSourceFile(inserted.value);
+}
+function formatOpsError(error, sourceFile) {
+  if (error instanceof PatchError) {
+    return error.message;
+  }
+  return flatMapErrors(error, e => formatSyntaxError(e, sourceFile)).join("\n");
+}
+
 /**
  * Replays a `val debug` snapshot: applies its patches the way /save does and
  * validates the result.
@@ -8892,4 +10555,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createFixPatch, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, findAndEvalValConfigFile, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, hasRemoteFileSchema, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };
+export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, hasRemoteFileSchema, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };