@valbuild/shared 0.99.1 → 0.100.0

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -19,6 +19,12 @@ type CookieValue = EnableCookieValue | {
         expires: Date;
     };
 };
+/**
+ * Upper bound on how many `.jsonValues()` entries one `/json` request may ask
+ * for. Callers page through bigger sets; the Studio chunks its key windows to
+ * this. Shared so client and server agree on the limit.
+ */
+export declare const JSON_ENTRIES_BATCH_MAX = 100;
 export declare const Api: {
     "/draft/enable": {
         GET: {
@@ -395,6 +401,7 @@ export declare const Api: {
                     schemaSha: z.ZodString;
                     baseSha: z.ZodString;
                     patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    jsonEntriesSha: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -434,6 +441,7 @@ export declare const Api: {
                     }, z.core.$strip>;
                     profileId: z.ZodNullable<z.ZodString>;
                     mode: z.ZodUnion<readonly [z.ZodLiteral<"http">, z.ZodLiteral<"fs">]>;
+                    jsonEntriesSha: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"use-websocket">;
                     url: z.ZodString;
@@ -819,7 +827,7 @@ export declare const Api: {
                             message: z.ZodString;
                             value: z.ZodOptional<z.ZodUnknown>;
                             fatal: z.ZodOptional<z.ZodBoolean>;
-                            fixes: z.ZodOptional<z.ZodArray<z.ZodType<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files", unknown, z.core.$ZodTypeInternals<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files", unknown>>>>;
+                            fixes: z.ZodOptional<z.ZodArray<z.ZodType<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry", unknown, z.core.$ZodTypeInternals<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry", unknown>>>>;
                         }, z.core.$strip>>>>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>;
@@ -963,6 +971,68 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    "/json": {
+        GET: {
+            req: {
+                query: {
+                    path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    key: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                    keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    offset: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>, z.ZodTransform<number, string>>>;
+                    limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>, z.ZodTransform<number, string>>>;
+                    apply_patches: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+                    key: z.ZodString;
+                    content: z.ZodAny;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+                    entries: z.ZodArray<z.ZodObject<{
+                        key: z.ZodString;
+                        content: z.ZodAny;
+                    }, z.core.$strip>>;
+                    missing: z.ZodArray<z.ZodString>;
+                    errors: z.ZodArray<z.ZodObject<{
+                        key: z.ZodString;
+                        message: z.ZodString;
+                    }, z.core.$strip>>;
+                    offset: z.ZodOptional<z.ZodNumber>;
+                    limit: z.ZodOptional<z.ZodNumber>;
+                    total: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/ai/initialize": {
         POST: {
             req: {
@@ -1209,7 +1279,7 @@ type DefinedObject<T> = Pick<T, DefinedKeys<T>>;
  *
  * Do not change this without updating the ValRouter query parsing logic
  * */
-export type ValidQueryParamTypes = boolean | string | string[] | undefined;
+export type ValidQueryParamTypes = boolean | number | string | string[] | undefined;
 export type ApiEndpoint = {
     req: {
         path?: z.ZodString | z.ZodOptional<z.ZodString>;

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -1245,7 +1245,7 @@ var ValConfig = zod.z.object({
   gitCommit: zod.z.string().optional(),
   gitBranch: zod.z.string().optional()
 });
-var ValidationFixZ = zod.z.union([zod.z.literal("image:add-metadata"), zod.z.literal("image:check-metadata"), zod.z.literal("image:check-remote"), zod.z.literal("image:upload-remote"), zod.z.literal("image:download-remote"), zod.z.literal("images:check-remote"), zod.z.literal("images:upload-remote"), zod.z.literal("file:add-metadata"), zod.z.literal("file:check-metadata"), zod.z.literal("file:check-remote"), zod.z.literal("file:upload-remote"), zod.z.literal("file:download-remote"), zod.z.literal("files:check-remote"), zod.z.literal("files:upload-remote"), zod.z.literal("keyof:check-keys"), zod.z.literal("router:check-route"), zod.z.literal("images:check-unique-folder"), zod.z.literal("files:check-unique-folder"), zod.z.literal("images:check-all-files"), zod.z.literal("files:check-all-files")]);
+var ValidationFixZ = zod.z.union([zod.z.literal("image:add-metadata"), zod.z.literal("image:check-metadata"), zod.z.literal("image:check-remote"), zod.z.literal("image:upload-remote"), zod.z.literal("image:download-remote"), zod.z.literal("images:check-remote"), zod.z.literal("images:upload-remote"), zod.z.literal("file:add-metadata"), zod.z.literal("file:check-metadata"), zod.z.literal("file:check-remote"), zod.z.literal("file:upload-remote"), zod.z.literal("file:download-remote"), zod.z.literal("files:check-remote"), zod.z.literal("files:upload-remote"), zod.z.literal("keyof:check-keys"), zod.z.literal("router:check-route"), zod.z.literal("images:check-unique-folder"), zod.z.literal("files:check-unique-folder"), zod.z.literal("images:check-all-files"), zod.z.literal("files:check-all-files"), zod.z.literal("jsonValues:extract-entry")]);
 var ValidationError = zod.z.object({
   message: zod.z.string(),
   value: zod.z.unknown().optional(),
@@ -1294,6 +1294,18 @@ var onlyOneBooleanQueryParam = onlyOneStringQueryParam.refine(function (arg) {
 }, "Value must be true or false").transform(function (arg) {
   return arg === "true";
 });
+var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
+  return /^\d+$/.test(arg);
+}, "Value must be a non-negative whole number").transform(function (arg) {
+  return parseInt(arg, 10);
+});
+
+/**
+ * Upper bound on how many `.jsonValues()` entries one `/json` request may ask
+ * for. Callers page through bigger sets; the Studio chunks its key windows to
+ * this. Shared so client and server agree on the limit.
+ */
+var JSON_ENTRIES_BATCH_MAX = 100;
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1606,7 +1618,14 @@ var Api = {
           sourcesSha: zod.z.string(),
           schemaSha: zod.z.string(),
           baseSha: zod.z.string(),
-          patches: zod.z.array(zod.z.string()).optional()
+          patches: zod.z.array(zod.z.string()).optional(),
+          /**
+           * Fingerprint of the `.jsonValues()` entry files the client last saw.
+           * FS mode only: no other sha can see an entry file change, since a
+           * jsonValues module's source is markers and the content sits behind a
+           * thunk that `JSON.stringify` drops.
+           */
+          jsonEntriesSha: zod.z.string().optional()
         }).nullable(),
         cookies: {
           val_session: zod.z.string().optional()
@@ -1631,7 +1650,8 @@ var Api = {
           patches: zod.z.array(PatchId),
           config: ValConfig,
           profileId: zod.z.string().nullable(),
-          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")])
+          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
+          jsonEntriesSha: zod.z.string().optional()
         }), zod.z.object({
           type: zod.z.literal("use-websocket"),
           url: zod.z.string(),
@@ -1993,6 +2013,88 @@ var Api = {
       })])
     }
   },
+  // Loads the content of `.jsonValues()` record/router entries, so the Studio can
+  // lazily load just the entries it needs (instead of the whole record), and so
+  // the runtime can read draft edits in draft mode.
+  //
+  // Three request shapes, exactly one of which must be used:
+  //   1. `key=<k>`                 — ONE entry; responds `{path, key, content}`.
+  //   2. `keys=<k>&keys=<k2>&…`    — a BATCH; responds `{path, entries, missing, errors}`.
+  //   3. `offset=<n>&limit=<n>`    — a PAGE of every entry, in module key order;
+  //                                  responds as (2) plus `{offset, limit, total}`.
+  // (2) and (3) are what make loading many entries one round trip instead of N:
+  // the server resolves sources and pending patches ONCE per request, not per entry.
+  //
+  // Batch failures are per entry, never whole-request: a key with no entry lands in
+  // `missing`, a key whose `*.val.json` fails to load lands in `errors`. Only a
+  // missing/non-record MODULE is a 404.
+  //
+  // `apply_patches` defaults to TRUE (as on `/sources/~`): the server replays
+  // pending patches for the entry. The Studio passes `false` explicitly, because
+  // it owns in-flight client patches the server has not seen yet and applies
+  // them itself — letting the server apply them too would double-apply.
+  //
+  // Shape (3) REQUIRES `apply_patches=false`. Enumerating "every entry" from the
+  // base source would silently omit draft-added keys, and the only all-mode caller
+  // (the Studio) derives its key set from its own patched source anyway. Callers
+  // that need draft-aware enumeration pass explicit `keys`.
+  "/json": {
+    GET: {
+      req: {
+        query: {
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam.optional(),
+          keys: zod.z.array(zod.z.string()).max(JSON_ENTRIES_BATCH_MAX).optional(),
+          offset: onlyOneIntQueryParam.optional(),
+          limit: onlyOneIntQueryParam.refine(function (arg) {
+            return arg > 0 && arg <= JSON_ENTRIES_BATCH_MAX;
+          }, "limit must be between 1 and ".concat(JSON_ENTRIES_BATCH_MAX)).optional(),
+          apply_patches: onlyOneBooleanQueryParam.optional()
+        },
+        cookies: _defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional())
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse,
+      // Shape (1): single `key`.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          key: zod.z.string(),
+          // The entry's JSON content (or null if the entry has no value).
+          content: zod.z.any()
+        })
+      }),
+      // Shapes (2) and (3): `keys` or `offset`+`limit`.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          entries: zod.z.array(zod.z.object({
+            key: zod.z.string(),
+            // The entry's JSON content (or null if the entry has no value).
+            content: zod.z.any()
+          })),
+          // Requested keys that have no entry (neither committed nor drafted).
+          missing: zod.z.array(zod.z.string()),
+          // Requested keys whose content could not be loaded.
+          errors: zod.z.array(zod.z.object({
+            key: zod.z.string(),
+            message: zod.z.string()
+          })),
+          // All-mode only: the resolved window and the record's total key count.
+          offset: zod.z.number().optional(),
+          limit: zod.z.number().optional(),
+          total: zod.z.number().optional()
+        })
+      }), zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError
+      })])
+    }
+  },
   "/ai/initialize": {
     POST: {
       req: {
@@ -2180,6 +2282,8 @@ var Api = {
  *
  * Do not change this without updating the ValRouter query parsing logic
  * */
+// `number` is allowed because the client stringifies every query value before it
+// goes on the URL (see createValClient), so a numeric param round-trips fine.
 
 function _typeof(o) {
   "@babel/helpers - typeof";
@@ -3173,6 +3277,7 @@ exports.DEFAULT_ERROR_MESSAGE = DEFAULT_ERROR_MESSAGE;
 exports.DateOptions = DateOptions;
 exports.FileOptions = FileOptions;
 exports.ImageOptions = ImageOptions;
+exports.JSON_ENTRIES_BATCH_MAX = JSON_ENTRIES_BATCH_MAX;
 exports.ParentRef = ParentRef$1;
 exports.Patch = Patch;
 exports.PatchBlock = PatchBlock;

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -1245,7 +1245,7 @@ var ValConfig = zod.z.object({
   gitCommit: zod.z.string().optional(),
   gitBranch: zod.z.string().optional()
 });
-var ValidationFixZ = zod.z.union([zod.z.literal("image:add-metadata"), zod.z.literal("image:check-metadata"), zod.z.literal("image:check-remote"), zod.z.literal("image:upload-remote"), zod.z.literal("image:download-remote"), zod.z.literal("images:check-remote"), zod.z.literal("images:upload-remote"), zod.z.literal("file:add-metadata"), zod.z.literal("file:check-metadata"), zod.z.literal("file:check-remote"), zod.z.literal("file:upload-remote"), zod.z.literal("file:download-remote"), zod.z.literal("files:check-remote"), zod.z.literal("files:upload-remote"), zod.z.literal("keyof:check-keys"), zod.z.literal("router:check-route"), zod.z.literal("images:check-unique-folder"), zod.z.literal("files:check-unique-folder"), zod.z.literal("images:check-all-files"), zod.z.literal("files:check-all-files")]);
+var ValidationFixZ = zod.z.union([zod.z.literal("image:add-metadata"), zod.z.literal("image:check-metadata"), zod.z.literal("image:check-remote"), zod.z.literal("image:upload-remote"), zod.z.literal("image:download-remote"), zod.z.literal("images:check-remote"), zod.z.literal("images:upload-remote"), zod.z.literal("file:add-metadata"), zod.z.literal("file:check-metadata"), zod.z.literal("file:check-remote"), zod.z.literal("file:upload-remote"), zod.z.literal("file:download-remote"), zod.z.literal("files:check-remote"), zod.z.literal("files:upload-remote"), zod.z.literal("keyof:check-keys"), zod.z.literal("router:check-route"), zod.z.literal("images:check-unique-folder"), zod.z.literal("files:check-unique-folder"), zod.z.literal("images:check-all-files"), zod.z.literal("files:check-all-files"), zod.z.literal("jsonValues:extract-entry")]);
 var ValidationError = zod.z.object({
   message: zod.z.string(),
   value: zod.z.unknown().optional(),
@@ -1294,6 +1294,18 @@ var onlyOneBooleanQueryParam = onlyOneStringQueryParam.refine(function (arg) {
 }, "Value must be true or false").transform(function (arg) {
   return arg === "true";
 });
+var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
+  return /^\d+$/.test(arg);
+}, "Value must be a non-negative whole number").transform(function (arg) {
+  return parseInt(arg, 10);
+});
+
+/**
+ * Upper bound on how many `.jsonValues()` entries one `/json` request may ask
+ * for. Callers page through bigger sets; the Studio chunks its key windows to
+ * this. Shared so client and server agree on the limit.
+ */
+var JSON_ENTRIES_BATCH_MAX = 100;
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1606,7 +1618,14 @@ var Api = {
           sourcesSha: zod.z.string(),
           schemaSha: zod.z.string(),
           baseSha: zod.z.string(),
-          patches: zod.z.array(zod.z.string()).optional()
+          patches: zod.z.array(zod.z.string()).optional(),
+          /**
+           * Fingerprint of the `.jsonValues()` entry files the client last saw.
+           * FS mode only: no other sha can see an entry file change, since a
+           * jsonValues module's source is markers and the content sits behind a
+           * thunk that `JSON.stringify` drops.
+           */
+          jsonEntriesSha: zod.z.string().optional()
         }).nullable(),
         cookies: {
           val_session: zod.z.string().optional()
@@ -1631,7 +1650,8 @@ var Api = {
           patches: zod.z.array(PatchId),
           config: ValConfig,
           profileId: zod.z.string().nullable(),
-          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")])
+          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
+          jsonEntriesSha: zod.z.string().optional()
         }), zod.z.object({
           type: zod.z.literal("use-websocket"),
           url: zod.z.string(),
@@ -1993,6 +2013,88 @@ var Api = {
       })])
     }
   },
+  // Loads the content of `.jsonValues()` record/router entries, so the Studio can
+  // lazily load just the entries it needs (instead of the whole record), and so
+  // the runtime can read draft edits in draft mode.
+  //
+  // Three request shapes, exactly one of which must be used:
+  //   1. `key=<k>`                 — ONE entry; responds `{path, key, content}`.
+  //   2. `keys=<k>&keys=<k2>&…`    — a BATCH; responds `{path, entries, missing, errors}`.
+  //   3. `offset=<n>&limit=<n>`    — a PAGE of every entry, in module key order;
+  //                                  responds as (2) plus `{offset, limit, total}`.
+  // (2) and (3) are what make loading many entries one round trip instead of N:
+  // the server resolves sources and pending patches ONCE per request, not per entry.
+  //
+  // Batch failures are per entry, never whole-request: a key with no entry lands in
+  // `missing`, a key whose `*.val.json` fails to load lands in `errors`. Only a
+  // missing/non-record MODULE is a 404.
+  //
+  // `apply_patches` defaults to TRUE (as on `/sources/~`): the server replays
+  // pending patches for the entry. The Studio passes `false` explicitly, because
+  // it owns in-flight client patches the server has not seen yet and applies
+  // them itself — letting the server apply them too would double-apply.
+  //
+  // Shape (3) REQUIRES `apply_patches=false`. Enumerating "every entry" from the
+  // base source would silently omit draft-added keys, and the only all-mode caller
+  // (the Studio) derives its key set from its own patched source anyway. Callers
+  // that need draft-aware enumeration pass explicit `keys`.
+  "/json": {
+    GET: {
+      req: {
+        query: {
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam.optional(),
+          keys: zod.z.array(zod.z.string()).max(JSON_ENTRIES_BATCH_MAX).optional(),
+          offset: onlyOneIntQueryParam.optional(),
+          limit: onlyOneIntQueryParam.refine(function (arg) {
+            return arg > 0 && arg <= JSON_ENTRIES_BATCH_MAX;
+          }, "limit must be between 1 and ".concat(JSON_ENTRIES_BATCH_MAX)).optional(),
+          apply_patches: onlyOneBooleanQueryParam.optional()
+        },
+        cookies: _defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional())
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse,
+      // Shape (1): single `key`.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          key: zod.z.string(),
+          // The entry's JSON content (or null if the entry has no value).
+          content: zod.z.any()
+        })
+      }),
+      // Shapes (2) and (3): `keys` or `offset`+`limit`.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          entries: zod.z.array(zod.z.object({
+            key: zod.z.string(),
+            // The entry's JSON content (or null if the entry has no value).
+            content: zod.z.any()
+          })),
+          // Requested keys that have no entry (neither committed nor drafted).
+          missing: zod.z.array(zod.z.string()),
+          // Requested keys whose content could not be loaded.
+          errors: zod.z.array(zod.z.object({
+            key: zod.z.string(),
+            message: zod.z.string()
+          })),
+          // All-mode only: the resolved window and the record's total key count.
+          offset: zod.z.number().optional(),
+          limit: zod.z.number().optional(),
+          total: zod.z.number().optional()
+        })
+      }), zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError
+      })])
+    }
+  },
   "/ai/initialize": {
     POST: {
       req: {
@@ -2180,6 +2282,8 @@ var Api = {
  *
  * Do not change this without updating the ValRouter query parsing logic
  * */
+// `number` is allowed because the client stringifies every query value before it
+// goes on the URL (see createValClient), so a numeric param round-trips fine.
 
 function _typeof(o) {
   "@babel/helpers - typeof";
@@ -3173,6 +3277,7 @@ exports.DEFAULT_ERROR_MESSAGE = DEFAULT_ERROR_MESSAGE;
 exports.DateOptions = DateOptions;
 exports.FileOptions = FileOptions;
 exports.ImageOptions = ImageOptions;
+exports.JSON_ENTRIES_BATCH_MAX = JSON_ENTRIES_BATCH_MAX;
 exports.ParentRef = ParentRef$1;
 exports.Patch = Patch;
 exports.PatchBlock = PatchBlock;

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1241,7 +1241,7 @@ var ValConfig = z.object({
   gitCommit: z.string().optional(),
   gitBranch: z.string().optional()
 });
-var ValidationFixZ = z.union([z.literal("image:add-metadata"), z.literal("image:check-metadata"), z.literal("image:check-remote"), z.literal("image:upload-remote"), z.literal("image:download-remote"), z.literal("images:check-remote"), z.literal("images:upload-remote"), z.literal("file:add-metadata"), z.literal("file:check-metadata"), z.literal("file:check-remote"), z.literal("file:upload-remote"), z.literal("file:download-remote"), z.literal("files:check-remote"), z.literal("files:upload-remote"), z.literal("keyof:check-keys"), z.literal("router:check-route"), z.literal("images:check-unique-folder"), z.literal("files:check-unique-folder"), z.literal("images:check-all-files"), z.literal("files:check-all-files")]);
+var ValidationFixZ = z.union([z.literal("image:add-metadata"), z.literal("image:check-metadata"), z.literal("image:check-remote"), z.literal("image:upload-remote"), z.literal("image:download-remote"), z.literal("images:check-remote"), z.literal("images:upload-remote"), z.literal("file:add-metadata"), z.literal("file:check-metadata"), z.literal("file:check-remote"), z.literal("file:upload-remote"), z.literal("file:download-remote"), z.literal("files:check-remote"), z.literal("files:upload-remote"), z.literal("keyof:check-keys"), z.literal("router:check-route"), z.literal("images:check-unique-folder"), z.literal("files:check-unique-folder"), z.literal("images:check-all-files"), z.literal("files:check-all-files"), z.literal("jsonValues:extract-entry")]);
 var ValidationError = z.object({
   message: z.string(),
   value: z.unknown().optional(),
@@ -1290,6 +1290,18 @@ var onlyOneBooleanQueryParam = onlyOneStringQueryParam.refine(function (arg) {
 }, "Value must be true or false").transform(function (arg) {
   return arg === "true";
 });
+var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
+  return /^\d+$/.test(arg);
+}, "Value must be a non-negative whole number").transform(function (arg) {
+  return parseInt(arg, 10);
+});
+
+/**
+ * Upper bound on how many `.jsonValues()` entries one `/json` request may ask
+ * for. Callers page through bigger sets; the Studio chunks its key windows to
+ * this. Shared so client and server agree on the limit.
+ */
+var JSON_ENTRIES_BATCH_MAX = 100;
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1602,7 +1614,14 @@ var Api = {
           sourcesSha: z.string(),
           schemaSha: z.string(),
           baseSha: z.string(),
-          patches: z.array(z.string()).optional()
+          patches: z.array(z.string()).optional(),
+          /**
+           * Fingerprint of the `.jsonValues()` entry files the client last saw.
+           * FS mode only: no other sha can see an entry file change, since a
+           * jsonValues module's source is markers and the content sits behind a
+           * thunk that `JSON.stringify` drops.
+           */
+          jsonEntriesSha: z.string().optional()
         }).nullable(),
         cookies: {
           val_session: z.string().optional()
@@ -1627,7 +1646,8 @@ var Api = {
           patches: z.array(PatchId),
           config: ValConfig,
           profileId: z.string().nullable(),
-          mode: z.union([z.literal("http"), z.literal("fs")])
+          mode: z.union([z.literal("http"), z.literal("fs")]),
+          jsonEntriesSha: z.string().optional()
         }), z.object({
           type: z.literal("use-websocket"),
           url: z.string(),
@@ -1989,6 +2009,88 @@ var Api = {
       })])
     }
   },
+  // Loads the content of `.jsonValues()` record/router entries, so the Studio can
+  // lazily load just the entries it needs (instead of the whole record), and so
+  // the runtime can read draft edits in draft mode.
+  //
+  // Three request shapes, exactly one of which must be used:
+  //   1. `key=<k>`                 — ONE entry; responds `{path, key, content}`.
+  //   2. `keys=<k>&keys=<k2>&…`    — a BATCH; responds `{path, entries, missing, errors}`.
+  //   3. `offset=<n>&limit=<n>`    — a PAGE of every entry, in module key order;
+  //                                  responds as (2) plus `{offset, limit, total}`.
+  // (2) and (3) are what make loading many entries one round trip instead of N:
+  // the server resolves sources and pending patches ONCE per request, not per entry.
+  //
+  // Batch failures are per entry, never whole-request: a key with no entry lands in
+  // `missing`, a key whose `*.val.json` fails to load lands in `errors`. Only a
+  // missing/non-record MODULE is a 404.
+  //
+  // `apply_patches` defaults to TRUE (as on `/sources/~`): the server replays
+  // pending patches for the entry. The Studio passes `false` explicitly, because
+  // it owns in-flight client patches the server has not seen yet and applies
+  // them itself — letting the server apply them too would double-apply.
+  //
+  // Shape (3) REQUIRES `apply_patches=false`. Enumerating "every entry" from the
+  // base source would silently omit draft-added keys, and the only all-mode caller
+  // (the Studio) derives its key set from its own patched source anyway. Callers
+  // that need draft-aware enumeration pass explicit `keys`.
+  "/json": {
+    GET: {
+      req: {
+        query: {
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam.optional(),
+          keys: z.array(z.string()).max(JSON_ENTRIES_BATCH_MAX).optional(),
+          offset: onlyOneIntQueryParam.optional(),
+          limit: onlyOneIntQueryParam.refine(function (arg) {
+            return arg > 0 && arg <= JSON_ENTRIES_BATCH_MAX;
+          }, "limit must be between 1 and ".concat(JSON_ENTRIES_BATCH_MAX)).optional(),
+          apply_patches: onlyOneBooleanQueryParam.optional()
+        },
+        cookies: _defineProperty({}, VAL_SESSION_COOKIE, z.string().optional())
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse,
+      // Shape (1): single `key`.
+      z.object({
+        status: z.literal(200),
+        json: z.object({
+          path: ModuleFilePath,
+          key: z.string(),
+          // The entry's JSON content (or null if the entry has no value).
+          content: z.any()
+        })
+      }),
+      // Shapes (2) and (3): `keys` or `offset`+`limit`.
+      z.object({
+        status: z.literal(200),
+        json: z.object({
+          path: ModuleFilePath,
+          entries: z.array(z.object({
+            key: z.string(),
+            // The entry's JSON content (or null if the entry has no value).
+            content: z.any()
+          })),
+          // Requested keys that have no entry (neither committed nor drafted).
+          missing: z.array(z.string()),
+          // Requested keys whose content could not be loaded.
+          errors: z.array(z.object({
+            key: z.string(),
+            message: z.string()
+          })),
+          // All-mode only: the resolved window and the record's total key count.
+          offset: z.number().optional(),
+          limit: z.number().optional(),
+          total: z.number().optional()
+        })
+      }), z.object({
+        status: z.literal(400),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      })])
+    }
+  },
   "/ai/initialize": {
     POST: {
       req: {
@@ -2176,6 +2278,8 @@ var Api = {
  *
  * Do not change this without updating the ValRouter query parsing logic
  * */
+// `number` is allowed because the client stringifies every query value before it
+// goes on the URL (see createValClient), so a numeric param round-trips fine.
 
 function _typeof(o) {
   "@babel/helpers - typeof";
@@ -3164,4 +3268,4 @@ function resolveSchemaSourceFixes(validationErrors, snapshot) {
   return result;
 }
 
-export { Api, DEFAULT_ERROR_MESSAGE, DateOptions, FileOptions, ImageOptions, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RichTextOptions, SerializedArraySchema, SerializedBooleanSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedStringSchema, SerializedUnionSchema, SharedValConfig, VAL_AI_SESSION_STORAGE_KEY, VAL_CONFIG_SESSION_STORAGE_KEY, VAL_ENABLE_COOKIE_NAME, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_THEME_SESSION_STORAGE_KEY, ValCommit, ValDeployment, createRegExpFromPattern, createValClient, filterRoutesByPatterns, findSimilar, getErrorMessageFromUnknownJson, getNextAppRouterSitemapTree, getNextAppRouterSourceFolder, getPatternFromModuleFilePath, getRoutesOf, getRoutesWithModulePaths, levenshtein, parseRoutePattern, remirrorToRichTextSource, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, richTextToRemirror, urlOf, validateRoutePatterns };
+export { Api, DEFAULT_ERROR_MESSAGE, DateOptions, FileOptions, ImageOptions, JSON_ENTRIES_BATCH_MAX, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RichTextOptions, SerializedArraySchema, SerializedBooleanSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedStringSchema, SerializedUnionSchema, SharedValConfig, VAL_AI_SESSION_STORAGE_KEY, VAL_CONFIG_SESSION_STORAGE_KEY, VAL_ENABLE_COOKIE_NAME, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_THEME_SESSION_STORAGE_KEY, ValCommit, ValDeployment, createRegExpFromPattern, createValClient, filterRoutesByPatterns, findSimilar, getErrorMessageFromUnknownJson, getNextAppRouterSitemapTree, getNextAppRouterSourceFolder, getPatternFromModuleFilePath, getRoutesOf, getRoutesWithModulePaths, levenshtein, parseRoutePattern, remirrorToRichTextSource, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, richTextToRemirror, urlOf, validateRoutePatterns };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.99.1",
+  "version": "0.100.0",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "zod": "^4.3.5",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.99.1"
+    "@valbuild/core": "0.100.0"
   },
   "files": [
     "dist",