@valbuild/server 0.139.0 → 0.139.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @valbuild/server
 
+## 0.139.1
+
+### Patch Changes
+
+- [#781](https://github.com/valbuild/val/pull/781) [`5ea70ce`](https://github.com/valbuild/val/commit/5ea70cefde3c74961cfa76b4a5f4c333b850b60a) Thanks [@freekh](https://github.com/freekh)! - Every open Studio now shows the same changes, staged the same way, as a reload would.
+
+  - Staging or unstaging a change in one browser or tab now shows up in your other open Studios right away, without a reload, and publishing from any of them ships the same set.
+  - A change you stage before you have made any edit of your own is saved straight away, instead of being kept in the tab until your first edit and lost if you reloaded first.
+  - If staging a change fails, the Studio now goes back to showing what is actually saved, instead of keeping the failed change on screen until a reload.
+
+  This needs the Val Build content service released alongside this version.
+
+- Updated dependencies [[`238057d`](https://github.com/valbuild/val/commit/238057d2f17a6bdd22d0bd4316dd8e3a8843a85d), [`8f08418`](https://github.com/valbuild/val/commit/8f0841882d13c991d31dfbb03dd4873c9ab636b4), [`238057d`](https://github.com/valbuild/val/commit/238057d2f17a6bdd22d0bd4316dd8e3a8843a85d), [`db13bed`](https://github.com/valbuild/val/commit/db13bed902f9f9147feb5be07ce47fe8b5b143f9), [`5ea70ce`](https://github.com/valbuild/val/commit/5ea70cefde3c74961cfa76b4a5f4c333b850b60a)]:
+  - @valbuild/ui@0.139.1
+  - @valbuild/core@0.139.1
+  - @valbuild/shared@0.139.1
+
 ## 0.139.0
 
 ### Patch Changes

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

@@ -2,6 +2,7 @@ import { MediaSource, FileMetadata, FileSource, ImageMetadata, ModuleFilePath, P
 import { result } from "@valbuild/core/fp";
 import { JSONValue, ParentRef, Patch, PatchError } from "@valbuild/core/patch";
 import type { HistoryError } from "./history/HistoryError.js";
+import type { PatchGroupT } from "@valbuild/shared/internal";
 import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
 import { ValSyntaxError, ValSyntaxErrorTree } from "./patch/ts/syntax.js";
 import { ParentPatchId } from "@valbuild/core";
@@ -897,6 +898,14 @@ export type OrderedPatches = {
      * reasons.
      */
     headVersion?: number;
+    /**
+     * Every group on the branch and which of these patches each holds, read in
+     * the same transaction as the list and {@link headVersion}.
+     *
+     * Absent where the content service has no groups, or predates sending them
+     * here. Only `ValOpsHttp` fills it.
+     */
+    patchGroups?: PatchGroupT[];
     error?: GenericErrorMessage;
     errors?: PatchReadError[];
     unauthorized?: boolean;
@@ -912,6 +921,8 @@ export type OrderedPatchesMetadata = {
     headPatchId?: OrderedPatches["headPatchId"];
     /** See {@link OrderedPatches.headVersion}. */
     headVersion?: OrderedPatches["headVersion"];
+    /** See {@link OrderedPatches.patchGroups}. */
+    patchGroups?: OrderedPatches["patchGroups"];
     error?: GenericErrorMessage;
     errors?: OrderedPatches["errors"];
     unauthorized?: boolean;

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

@@ -22,6 +22,8 @@ declare const ModuleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.
 export declare function ownBranchVersion(headVersions: Record<string, number> | undefined, branch: string | undefined): number | undefined;
 export type PatchGroupMutationResult = {
     patchIds: PatchId[];
+    patchGroupId: string | null;
+    headVersion?: number;
     status?: undefined;
     error?: undefined;
 } | {
@@ -337,6 +339,8 @@ export declare class ValOpsHttp extends ValOps {
         headVersion?: number;
         /** The newest commit, which is the publish head. */
         headCommitSha?: string;
+        /** Who holds what, at `headVersion`. See {@link OrderedPatches.patchGroups}. */
+        patchGroups?: PatchGroupT[];
     } | {
         type: "error";
         error: GenericErrorMessage;
@@ -374,7 +378,12 @@ export declare class ValOpsHttp extends ValOps {
      * same stamp the patch row carries — so which client wrote a row stays
      * legible after the fact.
      */
-    stagePatches(patchGroupId: string, 
+    stagePatches(
+    /**
+     * The group to stage into, or `undefined` for the caller's open group on
+     * this branch — `~` on the content API, which creates it if there is none.
+     */
+    patchGroupId: string | undefined, 
     /** What the user asked to stage. */
     patchIds: PatchId[], 
     /**
@@ -410,7 +419,9 @@ export declare class ValOpsHttp extends ValOps {
      * unstages everything built on top of it within its patch sets, and that is
      * what `withPatchIds` carries.
      */
-    unstagePatches(patchGroupId: string, 
+    unstagePatches(
+    /** See {@link stagePatches}. With no open group, there is nothing to remove. */
+    patchGroupId: string | undefined, 
     /** What the user asked to unstage. */
     patchIds: PatchId[], 
     /** What has to go with it: everything built on top of it. */
@@ -473,6 +484,12 @@ export declare class ValOpsHttp extends ValOps {
         message: string;
     }>;
     private fetchPatchGroups;
+    /**
+     * Which branch `~` means, where this build knows: the branch it reads
+     * `applicable/patches` on, so the group staged into is the group listed.
+     * Without one the content API uses the project's own, as it does for reads.
+     */
+    private ownGroupBranch;
     private mutatePatchGroup;
     protected saveSourceFilePatch(path: ModuleFilePath, patch: PatchT, patchId: PatchId, parentRef: ParentRefT, authorId: AuthorId | null, sessionId: string | null, patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     /**

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

@@ -8341,8 +8341,24 @@ const GetApplicablePatches = z.z.object({
     createdAt: z.z.string(),
     applied: z.z.object({
       commitSha: z.z.string()
-    }).nullable()
+    }).nullable(),
+    /**
+     * The groups this patch is a member of. Read in the SAME transaction as
+     * the list and its `headVersion`, which is the point: see
+     * `OrderedPatches.patchGroups`. Optional for an older content service.
+     */
+    patchGroupIds: z.z.array(z.z.string()).optional()
   })),
+  /**
+   * The groups on the branch, without their members — those are on the
+   * patches above. Optional for a content service that predates groups.
+   */
+  patchGroups: z.z.array(z.z.object({
+    patchGroupId: z.z.string(),
+    authorId: z.z.string().nullable(),
+    createdAt: z.z.string(),
+    publishedAt: z.z.string().nullable()
+  })).optional(),
   /**
    * The head of the chain. See `OrderedPatches.headPatchId`. Optional because
    * a content service that predates it sends nothing.
@@ -8597,8 +8613,11 @@ const PatchGroupsResponse = z.z.object({
   patchGroups: z.z.array(internal.PatchGroup)
 });
 const PatchGroupMutationResponse = z.z.object({
-  patchGroupId: z.z.string(),
-  patchIds: z.z.array(PatchId)
+  /** `null` for an unstage of `~` when the caller has no open group. */
+  patchGroupId: z.z.string().nullable(),
+  patchIds: z.z.array(PatchId),
+  /** The chain version the change committed at. Absent from an older `home`. */
+  headVersion: z.z.number().optional()
 });
 const NonceResponse = z.z.object({
   nonce: z.z.string(),
@@ -8612,6 +8631,9 @@ const NonceResponse = z.z.object({
  * in one request share an answer, and the next request asks again.
  */
 const PATCH_GROUPS_CACHE_MS = 1000;
+
+/** The content API's id for "the caller's open group on the branch". */
+const OWN_OPEN_GROUP = "~";
 class ValOpsHttp extends ValOps {
   authHeaders;
   root;
@@ -9241,6 +9263,15 @@ class ValOpsHttp extends ValOps {
       ...(allPatchData.headVersion !== undefined ? {
         headVersion: allPatchData.headVersion
       } : {}),
+      /*
+       * Who holds what, read with the list and its version. On every stat, so
+       * a Studio's view of the groups is never older than its view of the
+       * chain — which is what lets a stage made in another browser show here
+       * without a reload. See `OrderedPatches.patchGroups`.
+       */
+      ...(allPatchData.patchGroups !== undefined ? {
+        patchGroups: allPatchData.patchGroups
+      } : {}),
       /*
        * The PUBLISH head, which is not `commitSha`.
        *
@@ -9547,11 +9578,43 @@ class ValOpsHttp extends ValOps {
               });
             }
           }
+          /*
+           * Membership, folded from the per-patch annotation onto the groups.
+           *
+           * From THIS response and not from `GET /patch-groups`, because only
+           * this one is consistent with the list and the version beside it:
+           * the content service reads all three in one transaction. A group
+           * list fetched separately can be older or newer than the chain it is
+           * shown with — and the Studio decides what an editor sees, and what
+           * a publish ships, from the pair.
+           *
+           * A group holding none of the listed patches is still listed, with
+           * no members: "groups exist and you hold nothing here" is a real
+           * answer, and different from "this content service has no groups".
+           */
+          let patchGroups;
+          if (data.patchGroups !== undefined) {
+            const members = new Map();
+            for (const patch of data.patches) {
+              for (const groupId of patch.patchGroupIds ?? []) {
+                const list = members.get(groupId) ?? [];
+                list.push(patch.patchId);
+                members.set(groupId, list);
+              }
+            }
+            patchGroups = data.patchGroups.map(group => ({
+              ...group,
+              patchIds: members.get(group.patchGroupId) ?? []
+            }));
+          }
           return {
             commits,
             deployments,
             patches,
             errors,
+            ...(patchGroups !== undefined ? {
+              patchGroups
+            } : {}),
             ...(data.headPatchId !== undefined ? {
               headPatchId: data.headPatchId
             } : {}),
@@ -9609,7 +9672,12 @@ class ValOpsHttp extends ValOps {
    * same stamp the patch row carries — so which client wrote a row stays
    * legible after the fact.
    */
-  async stagePatches(patchGroupId, /** What the user asked to stage. */
+  async stagePatches(
+  /**
+   * The group to stage into, or `undefined` for the caller's open group on
+   * this branch — `~` on the content API, which creates it if there is none.
+   */
+  patchGroupId, /** What the user asked to stage. */
   patchIds,
   /**
    * What has to come with it, because the staged patches are written on top
@@ -9641,10 +9709,11 @@ class ValOpsHttp extends ValOps {
     // Encoded: patchGroupId arrives in a request body, so an unencoded value
     // like "../../commit" would reach a different endpoint carrying this
     // project's auth headers.
-    `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
       withPatchIds,
-      coreVersion: core.Internal.VERSION.core
+      coreVersion: core.Internal.VERSION.core,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9655,13 +9724,15 @@ class ValOpsHttp extends ValOps {
    * unstages everything built on top of it within its patch sets, and that is
    * what `withPatchIds` carries.
    */
-  async unstagePatches(patchGroupId, /** What the user asked to unstage. */
+  async unstagePatches(/** See {@link stagePatches}. With no open group, there is nothing to remove. */
+  patchGroupId, /** What the user asked to unstage. */
   patchIds, /** What has to go with it: everything built on top of it. */
   withPatchIds, /** See {@link stagePatches} — the content API's half of the ownership check. */
   authorId) {
-    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
-      withPatchIds
+      withPatchIds,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9776,6 +9847,17 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
+
+  /**
+   * Which branch `~` means, where this build knows: the branch it reads
+   * `applicable/patches` on, so the group staged into is the group listed.
+   * Without one the content API uses the project's own, as it does for reads.
+   */
+  ownGroupBranch() {
+    return this.git ? {
+      branch: this.git.branch
+    } : {};
+  }
   async mutatePatchGroup(method, path, body,
   /**
    * WHO is asking. Sent as `x-val-profile-id`, which is what the content API
@@ -9812,7 +9894,11 @@ class ValOpsHttp extends ValOps {
         const parsed = PatchGroupMutationResponse.safeParse(await res.json());
         if (parsed.success) {
           return {
-            patchIds: parsed.data.patchIds
+            patchIds: parsed.data.patchIds,
+            patchGroupId: parsed.data.patchGroupId,
+            ...(parsed.data.headVersion !== undefined ? {
+              headVersion: parsed.data.headVersion
+            } : {})
           };
         }
         return {
@@ -13444,7 +13530,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13457,14 +13543,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.stagePatches(patchGroupId, patchIds, withPatchIds,
         // Forwarded so the content API can refuse independently. This server
@@ -13483,8 +13574,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       },
@@ -13507,7 +13601,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13520,14 +13614,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.unstagePatches(patchGroupId, patchIds, withPatchIds, auth.id);
         if (res.error) {
@@ -13541,8 +13640,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       }

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

@@ -8341,8 +8341,24 @@ const GetApplicablePatches = z.z.object({
     createdAt: z.z.string(),
     applied: z.z.object({
       commitSha: z.z.string()
-    }).nullable()
+    }).nullable(),
+    /**
+     * The groups this patch is a member of. Read in the SAME transaction as
+     * the list and its `headVersion`, which is the point: see
+     * `OrderedPatches.patchGroups`. Optional for an older content service.
+     */
+    patchGroupIds: z.z.array(z.z.string()).optional()
   })),
+  /**
+   * The groups on the branch, without their members — those are on the
+   * patches above. Optional for a content service that predates groups.
+   */
+  patchGroups: z.z.array(z.z.object({
+    patchGroupId: z.z.string(),
+    authorId: z.z.string().nullable(),
+    createdAt: z.z.string(),
+    publishedAt: z.z.string().nullable()
+  })).optional(),
   /**
    * The head of the chain. See `OrderedPatches.headPatchId`. Optional because
    * a content service that predates it sends nothing.
@@ -8597,8 +8613,11 @@ const PatchGroupsResponse = z.z.object({
   patchGroups: z.z.array(internal.PatchGroup)
 });
 const PatchGroupMutationResponse = z.z.object({
-  patchGroupId: z.z.string(),
-  patchIds: z.z.array(PatchId)
+  /** `null` for an unstage of `~` when the caller has no open group. */
+  patchGroupId: z.z.string().nullable(),
+  patchIds: z.z.array(PatchId),
+  /** The chain version the change committed at. Absent from an older `home`. */
+  headVersion: z.z.number().optional()
 });
 const NonceResponse = z.z.object({
   nonce: z.z.string(),
@@ -8612,6 +8631,9 @@ const NonceResponse = z.z.object({
  * in one request share an answer, and the next request asks again.
  */
 const PATCH_GROUPS_CACHE_MS = 1000;
+
+/** The content API's id for "the caller's open group on the branch". */
+const OWN_OPEN_GROUP = "~";
 class ValOpsHttp extends ValOps {
   authHeaders;
   root;
@@ -9241,6 +9263,15 @@ class ValOpsHttp extends ValOps {
       ...(allPatchData.headVersion !== undefined ? {
         headVersion: allPatchData.headVersion
       } : {}),
+      /*
+       * Who holds what, read with the list and its version. On every stat, so
+       * a Studio's view of the groups is never older than its view of the
+       * chain — which is what lets a stage made in another browser show here
+       * without a reload. See `OrderedPatches.patchGroups`.
+       */
+      ...(allPatchData.patchGroups !== undefined ? {
+        patchGroups: allPatchData.patchGroups
+      } : {}),
       /*
        * The PUBLISH head, which is not `commitSha`.
        *
@@ -9547,11 +9578,43 @@ class ValOpsHttp extends ValOps {
               });
             }
           }
+          /*
+           * Membership, folded from the per-patch annotation onto the groups.
+           *
+           * From THIS response and not from `GET /patch-groups`, because only
+           * this one is consistent with the list and the version beside it:
+           * the content service reads all three in one transaction. A group
+           * list fetched separately can be older or newer than the chain it is
+           * shown with — and the Studio decides what an editor sees, and what
+           * a publish ships, from the pair.
+           *
+           * A group holding none of the listed patches is still listed, with
+           * no members: "groups exist and you hold nothing here" is a real
+           * answer, and different from "this content service has no groups".
+           */
+          let patchGroups;
+          if (data.patchGroups !== undefined) {
+            const members = new Map();
+            for (const patch of data.patches) {
+              for (const groupId of patch.patchGroupIds ?? []) {
+                const list = members.get(groupId) ?? [];
+                list.push(patch.patchId);
+                members.set(groupId, list);
+              }
+            }
+            patchGroups = data.patchGroups.map(group => ({
+              ...group,
+              patchIds: members.get(group.patchGroupId) ?? []
+            }));
+          }
           return {
             commits,
             deployments,
             patches,
             errors,
+            ...(patchGroups !== undefined ? {
+              patchGroups
+            } : {}),
             ...(data.headPatchId !== undefined ? {
               headPatchId: data.headPatchId
             } : {}),
@@ -9609,7 +9672,12 @@ class ValOpsHttp extends ValOps {
    * same stamp the patch row carries — so which client wrote a row stays
    * legible after the fact.
    */
-  async stagePatches(patchGroupId, /** What the user asked to stage. */
+  async stagePatches(
+  /**
+   * The group to stage into, or `undefined` for the caller's open group on
+   * this branch — `~` on the content API, which creates it if there is none.
+   */
+  patchGroupId, /** What the user asked to stage. */
   patchIds,
   /**
    * What has to come with it, because the staged patches are written on top
@@ -9641,10 +9709,11 @@ class ValOpsHttp extends ValOps {
     // Encoded: patchGroupId arrives in a request body, so an unencoded value
     // like "../../commit" would reach a different endpoint carrying this
     // project's auth headers.
-    `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
       withPatchIds,
-      coreVersion: core.Internal.VERSION.core
+      coreVersion: core.Internal.VERSION.core,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9655,13 +9724,15 @@ class ValOpsHttp extends ValOps {
    * unstages everything built on top of it within its patch sets, and that is
    * what `withPatchIds` carries.
    */
-  async unstagePatches(patchGroupId, /** What the user asked to unstage. */
+  async unstagePatches(/** See {@link stagePatches}. With no open group, there is nothing to remove. */
+  patchGroupId, /** What the user asked to unstage. */
   patchIds, /** What has to go with it: everything built on top of it. */
   withPatchIds, /** See {@link stagePatches} — the content API's half of the ownership check. */
   authorId) {
-    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
-      withPatchIds
+      withPatchIds,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9776,6 +9847,17 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
+
+  /**
+   * Which branch `~` means, where this build knows: the branch it reads
+   * `applicable/patches` on, so the group staged into is the group listed.
+   * Without one the content API uses the project's own, as it does for reads.
+   */
+  ownGroupBranch() {
+    return this.git ? {
+      branch: this.git.branch
+    } : {};
+  }
   async mutatePatchGroup(method, path, body,
   /**
    * WHO is asking. Sent as `x-val-profile-id`, which is what the content API
@@ -9812,7 +9894,11 @@ class ValOpsHttp extends ValOps {
         const parsed = PatchGroupMutationResponse.safeParse(await res.json());
         if (parsed.success) {
           return {
-            patchIds: parsed.data.patchIds
+            patchIds: parsed.data.patchIds,
+            patchGroupId: parsed.data.patchGroupId,
+            ...(parsed.data.headVersion !== undefined ? {
+              headVersion: parsed.data.headVersion
+            } : {})
           };
         }
         return {
@@ -13444,7 +13530,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13457,14 +13543,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.stagePatches(patchGroupId, patchIds, withPatchIds,
         // Forwarded so the content API can refuse independently. This server
@@ -13483,8 +13574,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       },
@@ -13507,7 +13601,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13520,14 +13614,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.unstagePatches(patchGroupId, patchIds, withPatchIds, auth.id);
         if (res.error) {
@@ -13541,8 +13640,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       }

package/dist/valbuild-server.esm.js

@@ -8304,8 +8304,24 @@ const GetApplicablePatches = z.object({
     createdAt: z.string(),
     applied: z.object({
       commitSha: z.string()
-    }).nullable()
+    }).nullable(),
+    /**
+     * The groups this patch is a member of. Read in the SAME transaction as
+     * the list and its `headVersion`, which is the point: see
+     * `OrderedPatches.patchGroups`. Optional for an older content service.
+     */
+    patchGroupIds: z.array(z.string()).optional()
   })),
+  /**
+   * The groups on the branch, without their members — those are on the
+   * patches above. Optional for a content service that predates groups.
+   */
+  patchGroups: z.array(z.object({
+    patchGroupId: z.string(),
+    authorId: z.string().nullable(),
+    createdAt: z.string(),
+    publishedAt: z.string().nullable()
+  })).optional(),
   /**
    * The head of the chain. See `OrderedPatches.headPatchId`. Optional because
    * a content service that predates it sends nothing.
@@ -8560,8 +8576,11 @@ const PatchGroupsResponse = z.object({
   patchGroups: z.array(PatchGroup)
 });
 const PatchGroupMutationResponse = z.object({
-  patchGroupId: z.string(),
-  patchIds: z.array(PatchId)
+  /** `null` for an unstage of `~` when the caller has no open group. */
+  patchGroupId: z.string().nullable(),
+  patchIds: z.array(PatchId),
+  /** The chain version the change committed at. Absent from an older `home`. */
+  headVersion: z.number().optional()
 });
 const NonceResponse = z.object({
   nonce: z.string(),
@@ -8575,6 +8594,9 @@ const NonceResponse = z.object({
  * in one request share an answer, and the next request asks again.
  */
 const PATCH_GROUPS_CACHE_MS = 1000;
+
+/** The content API's id for "the caller's open group on the branch". */
+const OWN_OPEN_GROUP = "~";
 class ValOpsHttp extends ValOps {
   authHeaders;
   root;
@@ -9204,6 +9226,15 @@ class ValOpsHttp extends ValOps {
       ...(allPatchData.headVersion !== undefined ? {
         headVersion: allPatchData.headVersion
       } : {}),
+      /*
+       * Who holds what, read with the list and its version. On every stat, so
+       * a Studio's view of the groups is never older than its view of the
+       * chain — which is what lets a stage made in another browser show here
+       * without a reload. See `OrderedPatches.patchGroups`.
+       */
+      ...(allPatchData.patchGroups !== undefined ? {
+        patchGroups: allPatchData.patchGroups
+      } : {}),
       /*
        * The PUBLISH head, which is not `commitSha`.
        *
@@ -9510,11 +9541,43 @@ class ValOpsHttp extends ValOps {
               });
             }
           }
+          /*
+           * Membership, folded from the per-patch annotation onto the groups.
+           *
+           * From THIS response and not from `GET /patch-groups`, because only
+           * this one is consistent with the list and the version beside it:
+           * the content service reads all three in one transaction. A group
+           * list fetched separately can be older or newer than the chain it is
+           * shown with — and the Studio decides what an editor sees, and what
+           * a publish ships, from the pair.
+           *
+           * A group holding none of the listed patches is still listed, with
+           * no members: "groups exist and you hold nothing here" is a real
+           * answer, and different from "this content service has no groups".
+           */
+          let patchGroups;
+          if (data.patchGroups !== undefined) {
+            const members = new Map();
+            for (const patch of data.patches) {
+              for (const groupId of patch.patchGroupIds ?? []) {
+                const list = members.get(groupId) ?? [];
+                list.push(patch.patchId);
+                members.set(groupId, list);
+              }
+            }
+            patchGroups = data.patchGroups.map(group => ({
+              ...group,
+              patchIds: members.get(group.patchGroupId) ?? []
+            }));
+          }
           return {
             commits,
             deployments,
             patches,
             errors,
+            ...(patchGroups !== undefined ? {
+              patchGroups
+            } : {}),
             ...(data.headPatchId !== undefined ? {
               headPatchId: data.headPatchId
             } : {}),
@@ -9572,7 +9635,12 @@ class ValOpsHttp extends ValOps {
    * same stamp the patch row carries — so which client wrote a row stays
    * legible after the fact.
    */
-  async stagePatches(patchGroupId, /** What the user asked to stage. */
+  async stagePatches(
+  /**
+   * The group to stage into, or `undefined` for the caller's open group on
+   * this branch — `~` on the content API, which creates it if there is none.
+   */
+  patchGroupId, /** What the user asked to stage. */
   patchIds,
   /**
    * What has to come with it, because the staged patches are written on top
@@ -9604,10 +9672,11 @@ class ValOpsHttp extends ValOps {
     // Encoded: patchGroupId arrives in a request body, so an unencoded value
     // like "../../commit" would reach a different endpoint carrying this
     // project's auth headers.
-    `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
       withPatchIds,
-      coreVersion: Internal.VERSION.core
+      coreVersion: Internal.VERSION.core,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9618,13 +9687,15 @@ class ValOpsHttp extends ValOps {
    * unstages everything built on top of it within its patch sets, and that is
    * what `withPatchIds` carries.
    */
-  async unstagePatches(patchGroupId, /** What the user asked to unstage. */
+  async unstagePatches(/** See {@link stagePatches}. With no open group, there is nothing to remove. */
+  patchGroupId, /** What the user asked to unstage. */
   patchIds, /** What has to go with it: everything built on top of it. */
   withPatchIds, /** See {@link stagePatches} — the content API's half of the ownership check. */
   authorId) {
-    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId ?? OWN_OPEN_GROUP)}/patches`, {
       patchIds,
-      withPatchIds
+      withPatchIds,
+      ...this.ownGroupBranch()
     }, authorId);
   }
 
@@ -9739,6 +9810,17 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
+
+  /**
+   * Which branch `~` means, where this build knows: the branch it reads
+   * `applicable/patches` on, so the group staged into is the group listed.
+   * Without one the content API uses the project's own, as it does for reads.
+   */
+  ownGroupBranch() {
+    return this.git ? {
+      branch: this.git.branch
+    } : {};
+  }
   async mutatePatchGroup(method, path, body,
   /**
    * WHO is asking. Sent as `x-val-profile-id`, which is what the content API
@@ -9775,7 +9857,11 @@ class ValOpsHttp extends ValOps {
         const parsed = PatchGroupMutationResponse.safeParse(await res.json());
         if (parsed.success) {
           return {
-            patchIds: parsed.data.patchIds
+            patchIds: parsed.data.patchIds,
+            patchGroupId: parsed.data.patchGroupId,
+            ...(parsed.data.headVersion !== undefined ? {
+              headVersion: parsed.data.headVersion
+            } : {})
           };
         }
         return {
@@ -13407,7 +13493,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13420,14 +13506,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.stagePatches(patchGroupId, patchIds, withPatchIds,
         // Forwarded so the content API can refuse independently. This server
@@ -13446,8 +13537,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       },
@@ -13470,7 +13564,7 @@ const ValServer = (valModules, options, callbacks) => {
           return {
             status: 200,
             json: {
-              patchGroupId,
+              patchGroupId: patchGroupId ?? null,
               patchIds: [...patchIds, ...withPatchIds]
             }
           };
@@ -13483,14 +13577,19 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
-        if (refusal !== null) {
-          return {
-            status: refusal.status,
-            json: {
-              message: refusal.message
-            }
-          };
+        // A named group is checked here as well as by the content API. No name
+        // is the caller's own open group, which the content API resolves from
+        // the profile it is sent — there is nothing here to check it against.
+        if (patchGroupId !== undefined) {
+          const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+          if (refusal !== null) {
+            return {
+              status: refusal.status,
+              json: {
+                message: refusal.message
+              }
+            };
+          }
         }
         const res = await serverOps.unstagePatches(patchGroupId, patchIds, withPatchIds, auth.id);
         if (res.error) {
@@ -13504,8 +13603,11 @@ const ValServer = (valModules, options, callbacks) => {
         return {
           status: 200,
           json: {
-            patchGroupId,
-            patchIds: res.patchIds
+            patchGroupId: res.patchGroupId,
+            patchIds: res.patchIds,
+            ...(res.headVersion !== undefined ? {
+              headVersion: res.headVersion
+            } : {})
           }
         };
       }

package/package.json

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