@valbuild/shared 0.99.1 → 0.101.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/dist/declarations/src/internal/zod/SerializedSchema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type SerializedSchema as SerializedSchemaT, type SerializedStringSchema as SerializedStringSchemaT, type SerializedLiteralSchema as SerializedLiteralSchemaT, type SerializedBooleanSchema as SerializedBooleanSchemaT, type SerializedNumberSchema as SerializedNumberSchemaT, type SerializedObjectSchema as SerializedObjectSchemaT, type SerializedArraySchema as SerializedArraySchemaT, type SerializedUnionSchema as SerializedUnionSchemaT, type SerializedRichTextSchema as SerializedRichTextSchemaT, type SerializedRichTextOptions as SerializedRichTextOptionsT, type SerializedRecordSchema as SerializedRecordSchemaT, type SerializedKeyOfSchema as SerializedKeyOfSchemaT, type SerializedRouteSchema as SerializedRouteSchemaT, type SerializedFileSchema as SerializedFileSchemaT, type SerializedDateSchema as SerializedDateSchemaT, type SerializedDateTimeSchema as SerializedDateTimeSchemaT, type SerializedImageSchema as SerializedImageSchemaT } from "@valbuild/core";
+import { type SerializedSchema as SerializedSchemaT, type SerializedStringSchema as SerializedStringSchemaT, type SerializedLiteralSchema as SerializedLiteralSchemaT, type SerializedBooleanSchema as SerializedBooleanSchemaT, type SerializedNumberSchema as SerializedNumberSchemaT, type SerializedObjectSchema as SerializedObjectSchemaT, type SerializedArraySchema as SerializedArraySchemaT, type SerializedUnionSchema as SerializedUnionSchemaT, type SerializedRichTextSchema as SerializedRichTextSchemaT, type SerializedRichTextOptions as SerializedRichTextOptionsT, type SerializedRecordSchema as SerializedRecordSchemaT, type SerializedKeyOfSchema as SerializedKeyOfSchemaT, type SerializedRouteSchema as SerializedRouteSchemaT, type SerializedFileSchema as SerializedFileSchemaT, type SerializedDateSchema as SerializedDateSchemaT, type SerializedDateTimeSchema as SerializedDateTimeSchemaT, type SerializedColorSchema as SerializedColorSchemaT, type SerializedImageSchema as SerializedImageSchemaT } from "@valbuild/core";
 export declare const SerializedStringSchema: z.ZodType<SerializedStringSchemaT>;
 export declare const SerializedLiteralSchema: z.ZodType<SerializedLiteralSchemaT>;
 export declare const SerializedBooleanSchema: z.ZodType<SerializedBooleanSchemaT>;
@@ -28,5 +28,15 @@ export declare const DateOptions: z.ZodObject<{
 }, z.core.$strip>;
 export declare const SerializedDateSchema: z.ZodType<SerializedDateSchemaT>;
 export declare const SerializedDateTimeSchema: z.ZodType<SerializedDateTimeSchemaT>;
+export declare const ColorOptions: z.ZodObject<{
+    format: z.ZodOptional<z.ZodEnum<{
+        hex: "hex";
+        rgb: "rgb";
+        hsl: "hsl";
+        oklch: "oklch";
+    }>>;
+    alpha: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const SerializedColorSchema: z.ZodType<SerializedColorSchemaT>;
 export declare const SerializedRouteSchema: z.ZodType<SerializedRouteSchemaT>;
 export declare const SerializedSchema: z.ZodType<SerializedSchemaT>;

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

@@ -1195,6 +1195,19 @@ var SerializedDateTimeSchema = zod.z.object({
   hidden: zod.z["boolean"]().optional(),
   description: zod.z.string().optional()
 });
+var ColorOptions = zod.z.object({
+  format: zod.z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
+  alpha: zod.z["boolean"]().optional()
+});
+var SerializedColorSchema = zod.z.object({
+  type: zod.z.literal("color"),
+  options: ColorOptions.optional(),
+  opt: zod.z["boolean"](),
+  customValidate: zod.z["boolean"]().optional(),
+  readonly: zod.z["boolean"]().optional(),
+  hidden: zod.z["boolean"]().optional(),
+  description: zod.z.string().optional()
+});
 var SerializedRouteSchema = zod.z.object({
   type: zod.z.literal("route"),
   options: zod.z.object({
@@ -1213,7 +1226,7 @@ var SerializedRouteSchema = zod.z.object({
   readonly: zod.z["boolean"]().optional(),
   hidden: zod.z["boolean"]().optional()
 });
-var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedImageSchema]);
+var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedImageSchema]);
 
 var ValCommit = zod.z.object({
   commitSha: zod.z.string(),
@@ -1245,7 +1258,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 +1307,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 +1631,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 +1663,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 +2026,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 +2295,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";
@@ -3169,10 +3286,12 @@ function resolveSchemaSourceFixes(validationErrors, snapshot) {
 }
 
 exports.Api = Api;
+exports.ColorOptions = ColorOptions;
 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;
@@ -3192,6 +3311,7 @@ exports.RemirrorTextMark = RemirrorTextMark;
 exports.RichTextOptions = RichTextOptions;
 exports.SerializedArraySchema = SerializedArraySchema;
 exports.SerializedBooleanSchema = SerializedBooleanSchema;
+exports.SerializedColorSchema = SerializedColorSchema;
 exports.SerializedDateSchema = SerializedDateSchema;
 exports.SerializedDateTimeSchema = SerializedDateTimeSchema;
 exports.SerializedFileSchema = SerializedFileSchema;

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

@@ -1195,6 +1195,19 @@ var SerializedDateTimeSchema = zod.z.object({
   hidden: zod.z["boolean"]().optional(),
   description: zod.z.string().optional()
 });
+var ColorOptions = zod.z.object({
+  format: zod.z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
+  alpha: zod.z["boolean"]().optional()
+});
+var SerializedColorSchema = zod.z.object({
+  type: zod.z.literal("color"),
+  options: ColorOptions.optional(),
+  opt: zod.z["boolean"](),
+  customValidate: zod.z["boolean"]().optional(),
+  readonly: zod.z["boolean"]().optional(),
+  hidden: zod.z["boolean"]().optional(),
+  description: zod.z.string().optional()
+});
 var SerializedRouteSchema = zod.z.object({
   type: zod.z.literal("route"),
   options: zod.z.object({
@@ -1213,7 +1226,7 @@ var SerializedRouteSchema = zod.z.object({
   readonly: zod.z["boolean"]().optional(),
   hidden: zod.z["boolean"]().optional()
 });
-var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedImageSchema]);
+var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedImageSchema]);
 
 var ValCommit = zod.z.object({
   commitSha: zod.z.string(),
@@ -1245,7 +1258,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 +1307,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 +1631,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 +1663,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 +2026,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 +2295,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";
@@ -3169,10 +3286,12 @@ function resolveSchemaSourceFixes(validationErrors, snapshot) {
 }
 
 exports.Api = Api;
+exports.ColorOptions = ColorOptions;
 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;
@@ -3192,6 +3311,7 @@ exports.RemirrorTextMark = RemirrorTextMark;
 exports.RichTextOptions = RichTextOptions;
 exports.SerializedArraySchema = SerializedArraySchema;
 exports.SerializedBooleanSchema = SerializedBooleanSchema;
+exports.SerializedColorSchema = SerializedColorSchema;
 exports.SerializedDateSchema = SerializedDateSchema;
 exports.SerializedDateTimeSchema = SerializedDateTimeSchema;
 exports.SerializedFileSchema = SerializedFileSchema;

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

@@ -1191,6 +1191,19 @@ var SerializedDateTimeSchema = z.object({
   hidden: z["boolean"]().optional(),
   description: z.string().optional()
 });
+var ColorOptions = z.object({
+  format: z["enum"](["hex", "rgb", "hsl", "oklch"]).optional(),
+  alpha: z["boolean"]().optional()
+});
+var SerializedColorSchema = z.object({
+  type: z.literal("color"),
+  options: ColorOptions.optional(),
+  opt: z["boolean"](),
+  customValidate: z["boolean"]().optional(),
+  readonly: z["boolean"]().optional(),
+  hidden: z["boolean"]().optional(),
+  description: z.string().optional()
+});
 var SerializedRouteSchema = z.object({
   type: z.literal("route"),
   options: z.object({
@@ -1209,7 +1222,7 @@ var SerializedRouteSchema = z.object({
   readonly: z["boolean"]().optional(),
   hidden: z["boolean"]().optional()
 });
-var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedImageSchema]);
+var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedImageSchema]);
 
 var ValCommit = z.object({
   commitSha: z.string(),
@@ -1241,7 +1254,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 +1303,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 +1627,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 +1659,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 +2022,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 +2291,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 +3281,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, ColorOptions, 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, SerializedColorSchema, 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.101.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.101.0"
   },
   "files": [
     "dist",