@valbuild/shared 0.120.0 → 0.122.0

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

@@ -897,6 +897,12 @@ function _asyncToGenerator(n) {
   };
 }
 
+/**
+ * JSON, recursively — the shape of a Source over the wire.
+ *
+ * Exported because history reads stored Sources back and needs the same
+ * definition; a second copy is a second thing to keep in step.
+ */
 var JSONValue = z.lazy(function () {
   return z.union([z.string(), z.number(), z["boolean"](), z["null"](), z.array(JSONValue), z.record(z.string(), JSONValue)]);
 });
@@ -1275,7 +1281,26 @@ 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, SerializedColorSchema, SerializedCodeSchema, SerializedImageSchema]);
+
+// A settings module, and each section inside one, serialize as this - the
+// shape is recursive because `items` holds sections which are themselves
+// settings schemas. `s.settings()` never writes render/preview/customValidate
+// (see core/src/schema/settings.ts), but they are accepted here because they
+// are part of the declared type.
+var SerializedSettingsSchema = z.lazy(function () {
+  return z.object({
+    type: z.literal("settings"),
+    render: FieldRender,
+    preview: z.literal(true).optional(),
+    items: z.record(z.string(), SerializedSchema),
+    opt: z["boolean"](),
+    customValidate: z["boolean"]().optional(),
+    readonly: z["boolean"]().optional(),
+    hidden: z["boolean"]().optional(),
+    description: z.string().optional()
+  });
+});
+var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
 var ValCommit = z.object({
   commitSha: z.string(),
@@ -1287,6 +1312,125 @@ var ValCommit = z.object({
   commitMessage: z.string().nullable()
 });
 
+/**
+ * The wire shapes for reading history.
+ *
+ * Here rather than in `@valbuild/server` because both sides of `/api/val` need
+ * them: the server builds these and the Studio parses them, and a second
+ * hand-written copy in the client is how the two drift.
+ *
+ * `HistoryError` is a closed union of everything that can go wrong
+ * reconstructing a commit - see `packages/server/src/history/HistoryError.ts`
+ * for what each one means. It travels as data rather than as a message because
+ * the Studio decides what to OFFER from it: a schema mismatch means "cannot
+ * restore this field", a missing source means "cannot restore this module at
+ * all", and a rendered string cannot be told apart.
+ */
+var HistoryError = z.discriminatedUnion("kind", [z.object({
+  kind: z.literal("commit-not-found"),
+  commitSha: z.string()
+}), z.object({
+  kind: z.literal("archive-unreadable"),
+  commitSha: z.string(),
+  message: z.string()
+}), z.object({
+  kind: z.literal("source-unavailable"),
+  moduleFilePath: z.string()
+}), z.object({
+  kind: z.literal("schema-unreadable"),
+  moduleFilePath: z.string(),
+  message: z.string()
+}), z.object({
+  kind: z.literal("file-unavailable"),
+  gitPath: z.string(),
+  message: z.string()
+}), z.object({
+  kind: z.literal("not-supported-in-fs-mode")
+}), z.object({
+  kind: z.literal("transport"),
+  message: z.string()
+})]);
+var HistoricalCommit = z.object({
+  commitSha: z.string(),
+  parentCommitSha: z.string(),
+  clientCommitSha: z.string(),
+  branch: z.string(),
+  createdBranch: z.string().nullable(),
+  creator: z.string().nullable(),
+  message: z.string().nullable(),
+  createdAt: z.string(),
+  seqNum: z.string(),
+  patchCount: z.number(),
+  /** False for commits made before history was recorded. */
+  hasArchive: z["boolean"]()
+});
+var FileChange = z.union([z.literal("added"), z.literal("modified"), z.literal("deleted")]);
+
+/**
+ * A binary file the commit touched - named, with a URL, and nothing fetched.
+ * Only an `<img src>` that mounts pays for the bytes.
+ */
+var BinaryFileRef = z.object({
+  gitPath: z.string(),
+  change: FileChange,
+  remote: z["boolean"](),
+  url: z.string()
+});
+var HistoricalModule = z.object({
+  /** The module's data at this commit. Null if deleted, or unreadable. */
+  source: JSONValue.nullable(),
+  /**
+   * The schema at this commit, already validated against THIS Val.
+   *
+   * Null with a `schema-unreadable` failure means the stored schema came from a
+   * Val whose schema format this one does not know — expected, not damage.
+   */
+  schema: SerializedSchema.nullable(),
+  patchIds: z.array(PatchId),
+  changedPaths: z.array(z.string()),
+  failures: z.array(HistoryError)
+});
+var HistoricalPatchSet = z.object({
+  commit: HistoricalCommit,
+  modules: z.record(z.string(), HistoricalModule),
+  patches: z.array(z.object({
+    patchId: PatchId,
+    moduleFilePath: z.string(),
+    patch: z.unknown(),
+    authorId: z.string().nullable(),
+    createdAt: z.string(),
+    baseSha: z.string(),
+    coreVersion: z.string()
+  })),
+  jsonEntries: z.record(z.string(), z.unknown()),
+  binaryFiles: z.array(BinaryFileRef),
+  warnings: z.array(HistoryError)
+});
+/**
+ * Whether the historical value can be written back as the project stands.
+ *
+ * Computed in the Studio, not on the server: the verdict depends on the current
+ * source and the current schema, both of which the client already holds, and it
+ * runs against the same worker-thread validator that validates ordinary edits.
+ * The types stay here because they are what a restore preview hands to the UI.
+ *
+ * `blocked` carries its reasons so a refusal can name the field and say why,
+ * rather than being an unexplained disabled button.
+ */
+var RestoreVerdict = z.union([z.object({
+  status: z.literal("restorable")
+}), z.object({
+  status: z.literal("blocked"),
+  reasons: z.array(HistoryError)
+})]);
+var ModuleComparison = z.object({
+  current: z.unknown().nullable(),
+  /** Paths where the commit's result and the current source differ: what a
+   * restore would undo. */
+  changedVsCurrent: z.array(z.string()),
+  verdict: RestoreVerdict
+});
+
 var ModuleFilePath = z.string().refine(function (_path) {
   return true;
 } // TODO: validation
@@ -1329,6 +1473,21 @@ var notFoundResponse = z.object({
 var GenericError = z.object({
   message: z.string()
 });
+
+/**
+ * A patch group: the set of patches one user has chosen to publish.
+ *
+ * Not a patch *set* — a patch set is computed from the schema and says which
+ * patches must move together; a patch group is curated and says which ones this
+ * user wants live. See `docs/independent-publish/PLAN.md`.
+ */
+var PatchGroup = z.object({
+  patchGroupId: z.string(),
+  authorId: z.string().nullable(),
+  createdAt: z.string(),
+  publishedAt: z.string().nullable(),
+  patchIds: z.array(PatchId)
+});
 var GenericPatchError = z.union([z.object({
   patchId: PatchId,
   message: z.string()
@@ -1541,48 +1700,6 @@ var Api = {
       })
     }
   },
-  "/session": {
-    GET: {
-      req: {
-        cookies: {
-          val_session: z.string().optional()
-        }
-      },
-      res: z.union([z.object({
-        status: z.literal(200),
-        json: z.object({
-          mode: z.union([z.literal("local"), z.literal("proxy")]),
-          enabled: z["boolean"]()
-        })
-      }), z.object({
-        status: z.union([
-        // TODO: Remove the ones we don't need.
-        z.literal(400), z.literal(401), z.literal(403), z.literal(404), z.literal(500), z.literal(501)]),
-        json: z.object({
-          message: z.string()
-        })
-      }), z.object({
-        status: z.literal(401),
-        json: z.object({
-          message: z.string(),
-          details: z.union([z.string(), z.object({
-            reason: z.string()
-          }), z.object({
-            sub: z.string(),
-            exp: z.number(),
-            token: z.string(),
-            org: z.string(),
-            project: z.string()
-          })])
-        })
-      }), z.object({
-        status: z.literal(500),
-        json: z.object({
-          message: z.string()
-        })
-      })])
-    }
-  },
   "/logout": {
     GET: {
       req: {
@@ -1710,6 +1827,30 @@ var Api = {
           schemaSha: z.string(),
           sourcesSha: z.string(),
           patches: z.array(PatchId),
+          /**
+           * Of `patches`, the ones that have already SHIPPED.
+           *
+           * A published patch stays in the chain with `appliedAt` set until
+           * the next deployment moves the base, so the id list alone cannot
+           * say which is which — and a client never re-fetches a record it
+           * already holds, so it never finds out on its own. Another
+           * author's publish then left that patch pending in your scope,
+           * your prefix gate read a hole in front of it, and Publish
+           * refused for a reason that had stopped being true.
+           *
+           * Optional: `fs` mode forgets published patches outright, and a
+           * client that ignores this behaves exactly as it did before.
+           */
+          appliedPatches: z.array(PatchId).optional(),
+          /**
+           * The newest commit, which is the PUBLISH head.
+           *
+           * Not `commitSha`: that is the commit this deployment serves and
+           * moves only when a new build lands. This moves the instant
+           * somebody publishes, which is what makes it the thing a client
+           * carries back to `/save` to say which world it decided against.
+           */
+          headCommitSha: z.string().optional(),
           /**
            * Unpublished changes the store threw away because it could not
            * read them.
@@ -1738,6 +1879,30 @@ var Api = {
           sourcesSha: z.string(),
           commitSha: z.string(),
           patches: z.array(PatchId),
+          /**
+           * Of `patches`, the ones that have already SHIPPED.
+           *
+           * A published patch stays in the chain with `appliedAt` set until
+           * the next deployment moves the base, so the id list alone cannot
+           * say which is which — and a client never re-fetches a record it
+           * already holds, so it never finds out on its own. Another
+           * author's publish then left that patch pending in your scope,
+           * your prefix gate read a hole in front of it, and Publish
+           * refused for a reason that had stopped being true.
+           *
+           * Optional: `fs` mode forgets published patches outright, and a
+           * client that ignores this behaves exactly as it did before.
+           */
+          appliedPatches: z.array(PatchId).optional(),
+          /**
+           * The newest commit, which is the PUBLISH head.
+           *
+           * Not `commitSha`: that is the commit this deployment serves and
+           * moves only when a new build lands. This moves the instant
+           * somebody publishes, which is what makes it the thing a client
+           * carries back to `/save` to say which world it decided against.
+           */
+          headCommitSha: z.string().optional(),
           commits: z.array(ValCommit),
           config: ValConfig,
           profileId: z.string().nullable(),
@@ -1807,6 +1972,26 @@ var Api = {
         query: {
           id: z.array(PatchId).min(1, "At least one patch id is required")
         },
+        body: z.object({
+          /*
+           * Patches that are NOT being deleted but must lose their patch
+           * group membership because these are.
+           *
+           * Deleting a patch out of the middle of a patch set leaves every
+           * group holding the rest with a non-prefix intersection, and a
+           * prefix is the one invariant a group has. Which patches those are
+           * needs the content schema, so the client computes the forward
+           * closure and sends it; the content API drops the memberships
+           * without touching the patches.
+           *
+           * In the BODY while the ids to delete are in the query, because
+           * this list is unbounded in the same way and the query string is
+           * already chunked to fit. Optional throughout: `fs` mode has no
+           * groups, and a client that predates this is deleting correctly,
+           * just not repairing.
+           */
+          unstagePatchIds: z.array(PatchId).optional()
+        }).optional(),
         cookies: {
           val_session: z.string().optional()
         }
@@ -1831,7 +2016,16 @@ var Api = {
             path: ModuleFilePath,
             patchId: PatchId,
             patch: z.any() // TODO: this should be Patch instead - we got a weird validation error: although input looks good, it still does not accept objects as values... Which it should do via the z.record(JSONValue) type
-          }))
+          })),
+          // Patch group membership. Sent with the patch itself, in one request, so
+          // there is no window in which a patch exists but belongs to no group.
+          // Absent means "the caller does not know about groups" - the server then
+          // behaves exactly as before.
+          patchGroupId: z.string().nullish(),
+          // What has to come with the patch: other patch ids that must join the
+          // same group for it to stay applicable. Computed on the client, which
+          // is the only side that has the schema needed to derive patch sets.
+          withPatchIds: z.array(PatchId).optional()
         }),
         cookies: {
           val_session: z.string().optional()
@@ -1857,7 +2051,8 @@ var Api = {
         status: z.literal(200),
         json: z.object({
           newPatchIds: z.array(PatchId),
-          parentRef: ParentRef
+          parentRef: ParentRef,
+          patchGroupId: z.string().optional()
         })
       })])
     },
@@ -1865,7 +2060,16 @@ var Api = {
       req: {
         query: {
           patch_id: z.array(PatchId).optional(),
-          exclude_patch_ops: onlyOneBooleanQueryParam.optional()
+          exclude_patch_ops: onlyOneBooleanQueryParam.optional(),
+          /**
+           * Include the patch group annotation in the answer.
+           *
+           * Off by default because the client CHUNKS this request — a long
+           * chain is several round trips — and the groups are a property of the
+           * branch, identical in every chunk. Asking on each one is N identical
+           * lookups against the content API to learn the same thing.
+           */
+          include_patch_groups: onlyOneBooleanQueryParam.optional()
         },
         cookies: {
           val_session: z.string().optional()
@@ -1894,8 +2098,12 @@ var Api = {
             authorId: z.string().nullable(),
             appliedAt: z.object({
               commitSha: z.string()
-            }).nullable()
+            }).nullable(),
+            // Which patch groups hold this patch. Optional so that FS mode, and
+            // any server that predates patch groups, can leave it out.
+            patchGroupIds: z.array(z.string()).optional()
           })),
+          patchGroups: z.array(PatchGroup).optional(),
           baseSha: z.string(),
           error: GenericError.optional(),
           errors: z.record(PatchId, GenericError).optional()
@@ -1903,6 +2111,91 @@ var Api = {
       })])
     }
   },
+  // Patch group membership. Both are idempotent set operations, and both take an
+  // already-closed set: the client computes the prefix closure (staging) or the
+  // forward closure (unstaging) because only the client has the schema needed to
+  // derive patch sets. See `docs/independent-publish/PLAN.md`.
+  "/patch-groups/~/patches": {
+    PUT: {
+      req: {
+        body: z.object({
+          patchGroupId: z.string(),
+          /** What the user asked to stage. */
+          patchIds: z.array(PatchId),
+          /*
+           * What has to come with it, because the staged patches are written on
+           * top of it.
+           *
+           * The content API records membership as `explicit` or `dependency`
+           * and reads what it is not told about as a dependency — so folding
+           * the two halves into `patchIds` files the patch someone clicked as
+           * something the closure dragged in.
+           */
+          withPatchIds: z.array(PatchId).optional()
+        }).refine(function (body) {
+          var _body$withPatchIds$le, _body$withPatchIds;
+          return body.patchIds.length > 0 || ((_body$withPatchIds$le = (_body$withPatchIds = body.withPatchIds) === null || _body$withPatchIds === void 0 ? void 0 : _body$withPatchIds.length) !== null && _body$withPatchIds$le !== void 0 ? _body$withPatchIds$le : 0) > 0;
+        },
+        // Either half alone is a real request: a stage of only what came with
+        // it happens when the deferred queue's scope filter drops everything
+        // the user originally clicked.
+        "At least one patch id is required"),
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, z.object({
+        status: z.literal(403),
+        json: GenericError
+      }), z.object({
+        // The group has already been published, so its membership is frozen.
+        status: z.literal(409),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          patchGroupId: z.string(),
+          patchIds: z.array(PatchId)
+        })
+      })])
+    },
+    DELETE: {
+      req: {
+        body: z.object({
+          patchGroupId: z.string(),
+          /** What the user asked to unstage. */
+          patchIds: z.array(PatchId),
+          /** What has to go with it: everything built on top of it. */
+          withPatchIds: z.array(PatchId).optional()
+        }).refine(function (body) {
+          var _body$withPatchIds$le2, _body$withPatchIds2;
+          return body.patchIds.length > 0 || ((_body$withPatchIds$le2 = (_body$withPatchIds2 = body.withPatchIds) === null || _body$withPatchIds2 === void 0 ? void 0 : _body$withPatchIds2.length) !== null && _body$withPatchIds$le2 !== void 0 ? _body$withPatchIds$le2 : 0) > 0;
+        }, "At least one patch id is required"),
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, z.object({
+        status: z.literal(403),
+        json: GenericError
+      }), z.object({
+        status: z.literal(409),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          patchGroupId: z.string(),
+          patchIds: z.array(PatchId)
+        })
+      })])
+    }
+  },
   "/schema": {
     GET: {
       req: {
@@ -1939,7 +2232,34 @@ var Api = {
           validate_sources: onlyOneBooleanQueryParam.optional(),
           validate_binary_files: onlyOneBooleanQueryParam.optional(),
           exclude_patches: onlyOneBooleanQueryParam.optional(),
-          apply_patches: onlyOneBooleanQueryParam.optional()
+          apply_patches: onlyOneBooleanQueryParam.optional(),
+          /**
+           * Apply ONLY these patches, rather than everything pending.
+           *
+           * This is what makes a draft-mode render match the caller's staged
+           * view. Without it `/sources/~` replays every pending patch on the
+           * branch, so a server-rendered preview shows other people's
+           * unpublished work — the one thing independent publish is for.
+           *
+           * Omitted means everything pending, which is the behaviour every
+           * existing caller has and must keep. An EMPTY array is a different
+           * answer and is honoured as one: a group holding nothing renders
+           * base.
+           */
+          patch_id: z.array(PatchId).optional(),
+          /**
+           * Apply only the patches in the CALLER'S OWN patch groups.
+           *
+           * The server resolves them from the session, so a draft render does
+           * not have to know its own group ids — which it cannot, since it has
+           * no client state. This is what makes `fetchVal` in draft mode show
+           * the person their own staged work rather than everybody's.
+           *
+           * Ignored when `patch_id` is given: an explicit list is a caller that
+           * already knows what it wants, and silently intersecting the two
+           * would make the narrower one invisible.
+           */
+          own_patch_groups_only: onlyOneBooleanQueryParam.optional()
         },
         cookies: {
           val_session: z.string().optional()
@@ -2018,7 +2338,35 @@ var Api = {
       req: {
         body: z.object({
           message: z.string().optional(),
-          patchIds: z.array(PatchId)
+          patchIds: z.array(PatchId),
+          /*
+           * The patch group this commit EMPTIES, if it empties one.
+           *
+           * Forwarded to the content API, which closes the group it names —
+           * and closes it unconditionally, without checking that the commit
+           * shipped all of it. So the client sends it only when the publish
+           * accounts for every patch the group still holds; a partial publish
+           * omits it and the group stays open with the rest in it.
+           *
+           * Optional, and absent in `fs` mode, which has no groups.
+           */
+          patchGroupId: z.string().optional(),
+          /*
+           * The newest commit this client knew about when it decided.
+           *
+           * Answered with 409 when the server sees a newer one, because then
+           * somebody else published between the review screen being read and
+           * Save being clicked, and what is about to ship was decided against a
+           * world that no longer exists.
+           *
+           * Git's own not-fast-forward guard does not cover this: `ValServer`
+           * fetches the chain and commits fresh at publish time, so the parent
+           * commit it sends is always the server's current one.
+           *
+           * Optional, so a client that does not track it publishes exactly as
+           * it did before.
+           */
+          expectedHeadCommitSha: z.string().optional()
         }),
         cookies: {
           val_session: z.string().optional()
@@ -2027,6 +2375,24 @@ var Api = {
       res: z.union([unauthorizedResponse, z.object({
         status: z.literal(200),
         json: z.object({
+          /**
+           * The commit this publish just made, which becomes the new publish
+           * head.
+           *
+           * Sent back because nothing else tells this client about its own
+           * commit in time. `headCommitSha` moves on a `/stat` response, and
+           * until the next poll lands the client still believes the
+           * PRE-publish head — so a second publish inside that window carried
+           * a stale `expectedHeadCommitSha`, the server compared it against
+           * the commit this same client had just made, and answered 409
+           * "someone else published". With auto-publish, which publishes on
+           * every pause in typing, that window is hit routinely and the
+           * message blames a colleague for the user's own commit.
+           *
+           * Optional: `fs` mode has no publish head, and neither does a
+           * server that predates this.
+           */
+          commitSha: z.string().optional(),
           /**
            * Unpublished changes the save threw away because they could not be
            * applied.
@@ -2043,12 +2409,61 @@ var Api = {
             message: z.string()
           })).optional()
         })
+      }),
+      /*
+       * The named patch group is not this caller's, or the lookup that would
+       * say so failed.
+       *
+       * Publishing may CLOSE a group, and closing somebody else's leaves
+       * their pending work in a closed group and in no open one. So `/save`
+       * runs the same ownership check stage and unstage do, and refuses the
+       * same way — see `refuseUnlessOwn`.
+       */
+      z.object({
+        status: z.literal(403),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
       }), z.object({
         status: z.literal(409),
-        json: z.object({
+        json: z.union([/** A group that has already shipped. See the 403 above. */
+        z.object({
+          message: z.string()
+        }), z.object({
           message: z.string(),
           isNotFastForward: z.literal(true)
-        })
+        }),
+        /*
+         * Somebody else published between this being decided and Save.
+         *
+         * Its own shape rather than another `isNotFastForward`, because
+         * they happen at different moments and mean different things to the
+         * user: that one is git refusing a commit, this one is refused
+         * BEFORE a commit is attempted, on a head the client named. Nothing
+         * was written either way, but only this one is answered by looking
+         * at the review screen again.
+         */
+        z.object({
+          message: z.string(),
+          headMoved: z.literal(true)
+        }),
+        /**
+         * The group this commit named has already been published.
+         *
+         * A third thing sharing 409, and flagged for the same reason
+         * `headMoved` is: read as a plain not-fast-forward it looks
+         * retryable, and it is the opposite — the id will never be writable
+         * again, so retrying reproduces it forever.
+         *
+         * It means this author published from somewhere else. The client
+         * forgets the id and falls back to the annotation, which is the
+         * same recovery a 409 on stage or unstage triggers.
+         */
+        z.object({
+          message: z.string(),
+          patchGroupPublished: z.literal(true)
+        })])
       }), z.object({
         status: z.literal(400),
         json: z.union([z.object({
@@ -2076,6 +2491,144 @@ var Api = {
       })])
     }
   },
+  // #region history
+  //
+  // Reading the past. Split across three routes on purpose, because they cache
+  // differently: a reconstructed commit cannot change and is immutable
+  // forever, the comparison against current source changes with every edit, and
+  // a file at a fixed commit is immutable too. Folding them together would mean
+  // the cheapest thing dragging the most expensive one's cache headers down to
+  // no-store.
+  "/history/commits": {
+    GET: {
+      req: {
+        query: {
+          branch: onlyOneStringQueryParam,
+          limit: onlyOneIntQueryParam.optional(),
+          /** The previous page's `nextCursor`. */
+          cursor: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          commits: z.array(HistoricalCommit),
+          nextCursor: z.string().nullable()
+        })
+      })])
+    }
+  },
+  /**
+   * One commit, reconstructed. IMMUTABLE for a given sha - it says nothing
+   * about the current source or schema, which is what lets it be cached
+   * forever and what makes comparing many commits cheap.
+   */
+  "/history/commit": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(200),
+        json: HistoricalPatchSet
+      })])
+    }
+  },
+  /**
+   * ONE module, as of a commit — including a commit that did not change it.
+   *
+   * `/history/commit` covers what a commit changed, which is the narrow case:
+   * navigate the history pane to anything else and there would be nothing to
+   * show. This answers "how did this module look at that point", which is the
+   * question someone comparing two panes is actually asking. Immutable for the
+   * same reason: what a commit left behind cannot change.
+   */
+  "/history/module": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          module_file_path: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          moduleFilePath: z.string(),
+          /**
+           * Null when history has no record of this module at or before the
+           * commit — it was last edited before recording started, or never.
+           * Distinct from a module the commit deleted.
+           */
+          module: HistoricalModule.nullable()
+        })
+      })])
+    }
+  },
+  /**
+   * One file as it was at one commit.
+   *
+   * The lazy half: `/history/commit` NAMES a commit's binary files and this is
+   * where their bytes come from, so nothing is fetched until an `<img>`
+   * actually mounts. A file at a fixed commit cannot change, so the response is
+   * immutable and the browser's own cache handles flipping between commits.
+   */
+  "/history/files": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          path: onlyOneStringQueryParam,
+          remote: onlyOneStringQueryParam.optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        body: z["instanceof"](ReadableStream)
+      })])
+    }
+  },
+  // #endregion history
   "/files": {
     GET: {
       req: {
@@ -2129,7 +2682,16 @@ var Api = {
           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()
+          apply_patches: onlyOneBooleanQueryParam.optional(),
+          /**
+           * The caller's own staged work, and nobody else's.
+           *
+           * The same flag `/sources/~` takes, and for the same reason — a draft
+           * page renders both, so a scoped module beside an unscoped
+           * `jsonValues` entry showed one person's view and everybody's pending
+           * work on the same screen.
+           */
+          own_patch_groups_only: onlyOneBooleanQueryParam.optional()
         },
         cookies: _defineProperty({}, VAL_SESSION_COOKIE, z.string().optional())
       },
@@ -2703,6 +3265,392 @@ var urlOf = function urlOf() {
   return "".concat(route);
 };
 
+/**
+ * Can this value, taken from one schema, be written into another?
+ *
+ * The question restore asks, and it is NOT the question validation asks.
+ * Validation checks a value against the schema it belongs to. This compares two
+ * schemas — the one a value was stored under and the one it is being written
+ * into — because a restore moves a value across a schema change, and possibly
+ * across paths.
+ *
+ * Three answers, not two. `unknown` is where the comparison genuinely cannot
+ * decide, and it exists so that an editor is told "we are not sure" rather than
+ * being given a confident answer we made up. Treating unknown as compatible
+ * writes values that break; treating it as incompatible blocks restores that
+ * would have been fine.
+ */
+
+var compatible = {
+  status: "compatible"
+};
+
+/**
+ * `Array.isArray` cannot narrow `JsonArray` out of `Json`, because it is
+ * `readonly Json[]` — so the check that reads naturally does not type. This
+ * predicate is that check, said once.
+ */
+function isJsonObject(value) {
+  return _typeof(value) === "object" && value !== null && !Array.isArray(value);
+}
+function incompatible(reason) {
+  return {
+    status: "incompatible",
+    reason: reason
+  };
+}
+
+/**
+ * "an object", "a string".
+ *
+ * Schema type names are data — `object`, `array`, `image` — so an interpolated
+ * "a" is wrong for three of them, in a sentence shown to editors the moment a
+ * restore is refused.
+ */
+function withArticle(type) {
+  return /^[aeiou]/i.test(type) ? "an ".concat(type) : "a ".concat(type);
+}
+
+/**
+ * A sentence an editor can act on, for the popup that explains a refusal.
+ *
+ * Kept beside the reasons rather than in the UI so that adding a reason without
+ * wording for it is a type error rather than a blank dialog.
+ */
+function explainIncompatible(reason) {
+  switch (reason.kind) {
+    case "type-changed":
+      return "This was ".concat(withArticle(reason.from), " and the field here is ").concat(withArticle(reason.to), ".");
+    case "no-matching-variant":
+      return "This does not match any of the shapes allowed here: ".concat(reason.variants.join(", "), ".");
+    case "unknown-field":
+      return "The old value has ".concat(reason.keys.length === 1 ? "a field" : "fields", " that no longer exist here: ").concat(reason.keys.join(", "), ".");
+    case "missing-required":
+      return "The field here needs ".concat(reason.keys.join(", "), ", which the old value does not have.");
+    case "not-optional":
+      return "The old value was empty, and this field cannot be empty.";
+    case "literal-changed":
+      return "This has to be exactly \"".concat(reason.to, "\", and the old value was \"").concat(reason.from, "\".");
+    case "different-module":
+      return "This points into ".concat(reason.to, ", and the old value pointed into ").concat(reason.from, ".");
+  }
+}
+
+/**
+ * The variant of a union that a value actually is.
+ *
+ * `undefined` when the value does not identify itself — which is a real answer,
+ * not a failure: it is what makes the caller return `unknown` rather than guess.
+ */
+function variantOf(schema, value) {
+  if (schema.type !== "union") {
+    return undefined;
+  }
+  // String union: the value IS the discriminator.
+  if (typeof schema.key !== "string") {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    return schema.items.find(function (item) {
+      return item.type === "literal" && item.value === value;
+    });
+  }
+  // Object union: the discriminator is a literal at `key`.
+  var discriminator = schema.key;
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  var tag = value[discriminator];
+  if (typeof tag !== "string") {
+    return undefined;
+  }
+  return schema.items.find(function (item) {
+    if (item.type !== "object") {
+      return false;
+    }
+    var keySchema = item.items[discriminator];
+    return (keySchema === null || keySchema === void 0 ? void 0 : keySchema.type) === "literal" && keySchema.value === tag;
+  });
+}
+function describeVariant(schema, key) {
+  if (schema.type === "literal") {
+    return schema.value;
+  }
+  if (schema.type === "object") {
+    var tag = schema.items[key];
+    if ((tag === null || tag === void 0 ? void 0 : tag.type) === "literal") {
+      return tag.value;
+    }
+  }
+  return schema.type;
+}
+function checkCompatibility(from, to) {
+  // Emptiness first: a null that lands in a field which cannot be empty is a
+  // break regardless of what the two schemas otherwise say.
+  if (from.value === null) {
+    return to.schema.opt ? compatible : incompatible({
+      kind: "not-optional"
+    });
+  }
+
+  // A changed union is not itself disqualifying. What matters is whether the
+  // variant being restored still has somewhere to go — comparing the unions
+  // wholesale would refuse a restore that is perfectly safe.
+  if (to.schema.type === "union") {
+    var key = typeof to.schema.key === "string" ? to.schema.key : "";
+    var _iterator = _createForOfIteratorHelper(to.schema.items),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var variant = _step.value;
+        if (checkCompatibility(from, {
+          schema: variant
+        }).status === "compatible") {
+          return compatible;
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return incompatible({
+      kind: "no-matching-variant",
+      variants: to.schema.items.map(function (item) {
+        return describeVariant(item, key);
+      })
+    });
+  }
+
+  // Coming FROM a union into something that is not one: only the variant this
+  // value actually is matters, so narrow before comparing.
+  if (from.schema.type === "union") {
+    var _variant = variantOf(from.schema, from.value);
+    if (_variant === undefined) {
+      return {
+        status: "unknown",
+        message: "The old value does not say which shape it is, so we cannot tell whether it fits here."
+      };
+    }
+    return checkCompatibility({
+      schema: _variant,
+      value: from.value
+    }, to);
+  }
+  if (from.schema.type !== to.schema.type) {
+    return incompatible({
+      kind: "type-changed",
+      from: from.schema.type,
+      to: to.schema.type
+    });
+  }
+  switch (to.schema.type) {
+    case "literal":
+      {
+        var fromValue = from.schema.type === "literal" ? from.schema.value : String(from.value);
+        return fromValue === to.schema.value ? compatible : incompatible({
+          kind: "literal-changed",
+          from: fromValue,
+          to: to.schema.value
+        });
+      }
+    case "object":
+      {
+        if (from.schema.type !== "object" || !isJsonObject(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not shaped like an object."
+          };
+        }
+        var _fromValue = from.value;
+        var target = to.schema.items;
+        var source = from.schema.items;
+
+        // Keys the old value carries that the field no longer has. Writing them
+        // would put data into a schema with nowhere to hold it.
+        var extra = Object.keys(source).filter(function (key) {
+          return !(key in target);
+        });
+        if (extra.length > 0) {
+          return incompatible({
+            kind: "unknown-field",
+            keys: extra
+          });
+        }
+
+        // Keys the field requires that the old value cannot supply.
+        var missing = Object.keys(target).filter(function (key) {
+          return !target[key].opt && !(key in source);
+        });
+        if (missing.length > 0) {
+          return incompatible({
+            kind: "missing-required",
+            keys: missing
+          });
+        }
+        var unknown = null;
+        for (var _i = 0, _Object$entries = Object.entries(target); _i < _Object$entries.length; _i++) {
+          var _fromValue$_key;
+          var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+            _key = _Object$entries$_i[0],
+            targetItem = _Object$entries$_i[1];
+          var sourceItem = source[_key];
+          if (sourceItem === undefined) {
+            continue; // optional and absent — already allowed above
+          }
+          var res = checkCompatibility({
+            schema: sourceItem,
+            value: (_fromValue$_key = _fromValue[_key]) !== null && _fromValue$_key !== void 0 ? _fromValue$_key : null
+          }, {
+            schema: targetItem
+          });
+          if (res.status === "incompatible") {
+            return res;
+          }
+          if (res.status === "unknown" && unknown === null) {
+            unknown = res;
+          }
+        }
+        return unknown !== null && unknown !== void 0 ? unknown : compatible;
+      }
+    case "array":
+      {
+        if (from.schema.type !== "array" || !Array.isArray(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not a list."
+          };
+        }
+        // An empty list has nothing to probe the item schema with. The item
+        // TYPES still have to agree, and that much can be decided without a
+        // value - so decide it rather than passing an empty list as proof.
+        if (from.value.length === 0) {
+          return from.schema.item.type === to.schema.item.type ? compatible : incompatible({
+            kind: "type-changed",
+            from: from.schema.item.type,
+            to: to.schema.item.type
+          });
+        }
+        var _unknown = null;
+        var _iterator2 = _createForOfIteratorHelper(from.value),
+          _step2;
+        try {
+          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+            var item = _step2.value;
+            var _res = checkCompatibility({
+              schema: from.schema.item,
+              value: item
+            }, {
+              schema: to.schema.item
+            });
+            if (_res.status === "incompatible") {
+              return _res;
+            }
+            if (_res.status === "unknown" && _unknown === null) {
+              _unknown = _res;
+            }
+          }
+        } catch (err) {
+          _iterator2.e(err);
+        } finally {
+          _iterator2.f();
+        }
+        return _unknown !== null && _unknown !== void 0 ? _unknown : compatible;
+      }
+    case "record":
+      {
+        if (from.schema.type !== "record" || !isJsonObject(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not a record."
+          };
+        }
+        var _unknown2 = null;
+        for (var _i2 = 0, _Object$values = Object.values(from.value); _i2 < _Object$values.length; _i2++) {
+          var entry = _Object$values[_i2];
+          var _res2 = checkCompatibility({
+            schema: from.schema.item,
+            value: entry !== null && entry !== void 0 ? entry : null
+          }, {
+            schema: to.schema.item
+          });
+          if (_res2.status === "incompatible") {
+            return _res2;
+          }
+          if (_res2.status === "unknown" && _unknown2 === null) {
+            _unknown2 = _res2;
+          }
+        }
+        return _unknown2 !== null && _unknown2 !== void 0 ? _unknown2 : compatible;
+      }
+    case "keyOf":
+      {
+        // A key is only meaningful against the module it indexes.
+        if (from.schema.type !== "keyOf") {
+          return compatible;
+        }
+        return from.schema.path === to.schema.path ? compatible : incompatible({
+          kind: "different-module",
+          from: from.schema.path,
+          to: to.schema.path
+        });
+      }
+    case "richtext":
+      {
+        // The options decide which nodes are legal, and comparing them properly
+        // means comparing node trees against them. Not yet done, and saying so is
+        // better than a confident answer we cannot back.
+        return {
+          status: "unknown",
+          message: "Rich text can be restored, but we cannot yet confirm every mark and block is still allowed here."
+        };
+      }
+    default:
+      // Primitives and media: same type is the whole test. Constraints
+      // (maxLength, accept, …) are validated on write, which reports them
+      // better than a schema comparison could.
+      return compatible;
+  }
+}
+
+/**
+ * The newest commit the client has been told about, or `null` if none.
+ *
+ * This is the **publish head**: unlike `baseSha`, which only moves once a
+ * deployment lands, it moves the instant somebody publishes. That makes it the
+ * one thing a client can carry to `/save` to say "this is the world I decided
+ * against" — and the only way the server can tell that somebody else has
+ * published since the review screen was read.
+ *
+ * In `shared` because both sides need the SAME answer: the client names a head
+ * and the server compares against one, so two implementations of "newest" is two
+ * ways to disagree about whether a publish is stale.
+ *
+ * By `createdAt` rather than by position, because the list's order is the
+ * content API's business and nothing here should depend on it. Ties keep the
+ * first seen, which is arbitrary and does not matter: two commits sharing a
+ * timestamp are equally "since", and either answer refuses the same publishes.
+ */
+function newestCommitSha(commits) {
+  var _newest$commitSha, _newest;
+  var newest = null;
+  var _iterator = _createForOfIteratorHelper(commits !== null && commits !== void 0 ? commits : []),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var commit = _step.value;
+      if (newest === null || commit.createdAt > newest.createdAt) {
+        newest = commit;
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return (_newest$commitSha = (_newest = newest) === null || _newest === void 0 ? void 0 : _newest.commitSha) !== null && _newest$commitSha !== void 0 ? _newest$commitSha : null;
+}
+
 var VAL_CONFIG_SESSION_STORAGE_KEY = "val-config";
 var VAL_THEME_SESSION_STORAGE_KEY = "val-theme";
 var VAL_AI_SESSION_STORAGE_KEY = "val-ai-session";
@@ -2718,14 +3666,6 @@ var SharedValConfig = z.object({
   ai: z.object({
     commitMessages: z.object({
       disabled: z["boolean"]().optional()
-    }).optional(),
-    chat: z.object({
-      experimental: z.object({
-        enable: z["boolean"]().optional()
-      }).optional(),
-      suggestions: z.array(z.string()).optional(),
-      title: z.string().optional(),
-      description: z.string().optional()
     }).optional()
   }).optional()
 });
@@ -3510,6 +4450,11 @@ function emptyOf(schema) {
     return [];
   } else if (schema.type === "record") {
     return {};
+  } else if (schema.type === "settings") {
+    // Not an object of empty sections: every settings key is optional, and
+    // absent IS the empty value. Filling the sections in would write a shape
+    // the project never asked for.
+    return {};
   } else if (schema.opt) {
     return null;
   } else if (schema.type === "richtext") {
@@ -4173,6 +5118,13 @@ function isSkippableFixCode(fix) {
       // rewriting the module) and saving does not repair it either, so surface
       // it: the message names the command (`val validate --fix`) that does.
       return false;
+    case "external:upload":
+      // Same shape as `jsonValues:extract-entry` — an entry inlined in a
+      // `.val.ts` that belongs elsewhere — and more emphatically not skippable.
+      // Fixing it writes to a live store, which is why even the CLI does it only
+      // under `val external upload` and never under a blanket `--fix`. Surfacing
+      // it is the whole point: someone has to decide.
+      return false;
     default:
       {
         return false;
@@ -4212,4 +5164,4 @@ function filterBlockingValidationErrors(validationErrors, schemas, sources) {
   return partitionValidationErrors(resolved).surfaced;
 }
 
-export { Api, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, FileOptions, ImageEncodeOption, 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, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedStringSchema, SerializedUnionSchema, SharedValConfig, VAL_AI_SESSION_STORAGE_KEY, VAL_CANVAS_MESSAGE, VAL_CANVAS_PARAM, VAL_CONFIG_SESSION_STORAGE_KEY, VAL_ENABLE_COOKIE_NAME, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_THEME_SESSION_STORAGE_KEY, ValCommit, ValDeployment, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, createRegExpFromPattern, createValClient, describeContainerAtPath, emptyOf, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, getErrorMessageFromUnknownJson, getInlineImgInfo, getNextAppRouterSitemapTree, getNextAppRouterSourceFolder, getPatternFromModuleFilePath, getRoutesOf, getRoutesWithModulePaths, getSourceAt, isRemoteSchema, isValCanvasFrame, isValCanvasPageMessage, isValCanvasStudioMessage, levenshtein, parseRoutePattern, partitionValidationErrors, remirrorToRichTextSource, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, toolNames, urlOf, validateRoutePatterns, withValCanvasParam };
+export { Api, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedUnionSchema, SharedValConfig, VAL_AI_SESSION_STORAGE_KEY, VAL_CANVAS_MESSAGE, VAL_CANVAS_PARAM, VAL_CONFIG_SESSION_STORAGE_KEY, VAL_ENABLE_COOKIE_NAME, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_THEME_SESSION_STORAGE_KEY, ValCommit, ValDeployment, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, checkCompatibility, createRegExpFromPattern, createValClient, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, getErrorMessageFromUnknownJson, getInlineImgInfo, getNextAppRouterSitemapTree, getNextAppRouterSourceFolder, getPatternFromModuleFilePath, getRoutesOf, getRoutesWithModulePaths, getSourceAt, isRemoteSchema, isValCanvasFrame, isValCanvasPageMessage, isValCanvasStudioMessage, levenshtein, newestCommitSha, parseRoutePattern, partitionValidationErrors, remirrorToRichTextSource, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, toolNames, urlOf, validateRoutePatterns, withValCanvasParam };