@valbuild/shared 0.138.4 → 0.139.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @valbuild/shared
 
+## 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 [[`db13bed`](https://github.com/valbuild/val/commit/db13bed902f9f9147feb5be07ce47fe8b5b143f9)]:
+  - @valbuild/core@0.139.1
+
+## 0.139.0
+
+### Minor Changes
+
+- [#776](https://github.com/valbuild/val/pull/776) [`3eb5031`](https://github.com/valbuild/val/commit/3eb503167ae466ee586303c95efcc14665129481) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `.render({ as: "inline" })` now goes on the list, not on its items.
+
+  You now write `s.array(item).render({ as: "inline" })` and `s.record(item).render({ as: "inline" })`. Each item is then edited in its own row instead of in a preview row you click into. The list decides. The item schema stays reusable, and a page builder made of tagged blocks needs nothing on each block:
+
+  ```ts
+  // before
+  s.array(
+    s.discriminatedUnion(
+      "type",
+      hero.render({ as: "inline" }),
+      text.render({ as: "inline" }),
+    ),
+  );
+
+  // after
+  s.array(s.discriminatedUnion("type", hero, text)).render({ as: "inline" });
+  ```
+
+  What changed:
+
+  - Only `s.array()`, `s.record()` and `s.keyOf()` have `.render(...)` now. On every other schema the method is gone, so the old placement shows up as a type error. Move the render out one level.
+  - The render only affects the list's own items. A list nested inside one of those items keeps its default unless it has its own `.render`.
+  - `s.router()`, `s.imageset()` and `s.fileset()` throw if you give them a render, because pages and media have their own editors.
+  - `s.keyOf(...).render({ as: "inline" })` means the same as before: the selected entry's content is shown below the dropdown.
+
+  **Watch for one case that still compiles:** an array or record that is itself the item of another list. `s.record(s.array(s.string()).render({ as: "inline" }))` used to show the record's arrays inline. Now it shows each array's strings inline. To keep the old layout, write `s.record(s.array(s.string())).render({ as: "inline" })`.
+
+### Patch Changes
+
+- Updated dependencies [[`3eb5031`](https://github.com/valbuild/val/commit/3eb503167ae466ee586303c95efcc14665129481)]:
+  - @valbuild/core@0.139.0
+
 ## 0.138.4
 
 ### Patch Changes

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

@@ -442,6 +442,13 @@ export declare const Api: {
                     headCommitSha: z.ZodOptional<z.ZodString>;
                     headPatchId: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                     headVersion: z.ZodOptional<z.ZodNumber>;
+                    patchGroups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        patchGroupId: z.ZodString;
+                        authorId: z.ZodNullable<z.ZodString>;
+                        createdAt: z.ZodString;
+                        publishedAt: z.ZodNullable<z.ZodString>;
+                        patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    }, z.core.$strip>>>;
                     commits: z.ZodArray<z.ZodObject<{
                         commitSha: z.ZodString;
                         clientCommitSha: z.ZodNullable<z.ZodString>;
@@ -863,7 +870,7 @@ export declare const Api: {
         PUT: {
             req: {
                 body: z.ZodObject<{
-                    patchGroupId: z.ZodString;
+                    patchGroupId: z.ZodOptional<z.ZodString>;
                     patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
                     withPatchIds: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                 }, z.core.$strip>;
@@ -894,15 +901,16 @@ export declare const Api: {
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
                 json: z.ZodObject<{
-                    patchGroupId: z.ZodString;
+                    patchGroupId: z.ZodNullable<z.ZodString>;
                     patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
         DELETE: {
             req: {
                 body: z.ZodObject<{
-                    patchGroupId: z.ZodString;
+                    patchGroupId: z.ZodOptional<z.ZodString>;
                     patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
                     withPatchIds: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                 }, z.core.$strip>;
@@ -933,8 +941,9 @@ export declare const Api: {
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
                 json: z.ZodObject<{
-                    patchGroupId: z.ZodString;
+                    patchGroupId: z.ZodNullable<z.ZodString>;
                     patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };

package/dist/declarations/src/internal/zod/SerializedSchema.d.ts

@@ -86,9 +86,6 @@ export declare const SerializedSettingsSchema: z.ZodType<SerializedSettingsSchem
  */
 export declare const SerializedValViewSchema: z.ZodObject<{
     type: z.ZodLiteral<"view">;
-    render: z.ZodOptional<z.ZodOptional<z.ZodObject<{
-        as: z.ZodLiteral<"inline">;
-    }, z.core.$strip>>>;
     moduleFilePath: z.ZodType<import("@valbuild/core").ModuleFilePath, unknown, z.core.$ZodTypeInternals<import("@valbuild/core").ModuleFilePath, unknown>>;
     opt: z.ZodLiteral<false>;
     readonly: z.ZodOptional<z.ZodBoolean>;

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

@@ -987,7 +987,8 @@ var _excluded = ["directory"];
 
 // A render is static config, so unlike a `preview` it travels WHOLE — this
 // is the field the editor reads the layout from. See `core/src/render.ts`.
-// Every field can carry `{ as: "inline" }`, and that is all a render says.
+// Only array, record and keyOf carry one, and `{ as: "inline" }` is all it
+// says. A stale `render` on any other schema is stripped here, harmlessly.
 // NB: these z.objects STRIP unknown keys, so a render variant that is not
 // declared here is silently dropped in transit — add it here when it is added
 // to `render.ts`.
@@ -1009,7 +1010,6 @@ var FieldRender = InlineRender.optional();
  * - those differ per schema, so there is nothing to share.
  */
 var commonSchemaFields = {
-  render: FieldRender,
   preview: zod.z.literal(true).optional(),
   // Whether the schema declares a `.validate()`. The function cannot serialize,
   // so this flag is what tells the Studio to run the custom validators on the
@@ -1068,6 +1068,7 @@ var SerializedObjectSchema = zod.z.lazy(function () {
 });
 var SerializedArraySchema = zod.z.lazy(function () {
   return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("array"),
     item: SerializedSchema,
     opt: zod.z["boolean"]()
@@ -1160,6 +1161,7 @@ var SerializedRichTextSchema = zod.z.object(getSitemapTree._objectSpread2(getSit
 }));
 var SerializedRecordSchema = zod.z.lazy(function () {
   return zod.z.preprocess(readLegacyDirectoryAsDir, zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("record"),
     item: SerializedSchema,
     opt: zod.z["boolean"](),
@@ -1176,6 +1178,7 @@ var SerializedRecordSchema = zod.z.lazy(function () {
 });
 var SerializedKeyOfSchema = zod.z.lazy(function () {
   return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("keyOf"),
     path: SourcePath,
     schema: zod.z.union([zod.z.object({
@@ -1235,7 +1238,6 @@ var SerializedCodeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemap
 }));
 var SerializedLocaleSchema = zod.z.object({
   type: zod.z.literal("locale"),
-  render: FieldRender,
   preview: zod.z.literal(true).optional(),
   opt: zod.z["boolean"](),
   customValidate: zod.z["boolean"]().optional(),
@@ -1261,7 +1263,7 @@ var SerializedRouteSchema = zod.z.object(getSitemapTree._objectSpread2(getSitema
 
 // 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
+// settings schemas. `s.settings()` never writes preview/customValidate
 // (see core/src/schema/settings.ts), but they are accepted here because they
 // are part of the declared type.
 var SerializedSettingsSchema = zod.z.lazy(function () {
@@ -1287,7 +1289,6 @@ var SerializedSettingsSchema = zod.z.lazy(function () {
  */
 var SerializedValViewSchema = zod.z.object({
   type: zod.z.literal("view"),
-  render: FieldRender.optional(),
   moduleFilePath: ModuleFilePath$1,
   opt: zod.z.literal(false),
   readonly: zod.z["boolean"]().optional(),
@@ -2027,6 +2028,14 @@ var Api = {
            * highest version. Optional, for the same reason `headPatchId` is.
            */
           headVersion: zod.z.number().optional(),
+          /**
+           * Every group on the branch and which listed patches it holds,
+           * read with the list and `headVersion`. What a Studio's view of
+           * the groups is taken from, so a stage or an unstage made in
+           * another browser reaches it with the next stat. Absent where
+           * the content service has no groups.
+           */
+          patchGroups: zod.z.array(PatchGroup).optional(),
           commits: zod.z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2426,7 +2435,12 @@ var Api = {
     PUT: {
       req: {
         body: zod.z.object({
-          patchGroupId: zod.z.string(),
+          /**
+           * The group to stage into. Absent means the caller's open group on
+           * the branch, created if there is none — which is what the Studio
+           * sends, so a stage never has to wait for a group to exist.
+           */
+          patchGroupId: zod.z.string().optional(),
           /** What the user asked to stage. */
           patchIds: zod.z.array(PatchId),
           /*
@@ -2464,15 +2478,23 @@ var Api = {
       }), zod.z.object({
         status: zod.z.literal(200),
         json: zod.z.object({
-          patchGroupId: zod.z.string(),
-          patchIds: zod.z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: zod.z.string().nullable(),
+          patchIds: zod.z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     },
     DELETE: {
       req: {
         body: zod.z.object({
-          patchGroupId: zod.z.string(),
+          /** See the PUT. Absent with no open group is a no-op. */
+          patchGroupId: zod.z.string().optional(),
           /** What the user asked to unstage. */
           patchIds: zod.z.array(PatchId),
           /** What has to go with it: everything built on top of it. */
@@ -2497,8 +2519,15 @@ var Api = {
       }), zod.z.object({
         status: zod.z.literal(200),
         json: zod.z.object({
-          patchGroupId: zod.z.string(),
-          patchIds: zod.z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: zod.z.string().nullable(),
+          patchIds: zod.z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     }

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

@@ -987,7 +987,8 @@ var _excluded = ["directory"];
 
 // A render is static config, so unlike a `preview` it travels WHOLE — this
 // is the field the editor reads the layout from. See `core/src/render.ts`.
-// Every field can carry `{ as: "inline" }`, and that is all a render says.
+// Only array, record and keyOf carry one, and `{ as: "inline" }` is all it
+// says. A stale `render` on any other schema is stripped here, harmlessly.
 // NB: these z.objects STRIP unknown keys, so a render variant that is not
 // declared here is silently dropped in transit — add it here when it is added
 // to `render.ts`.
@@ -1009,7 +1010,6 @@ var FieldRender = InlineRender.optional();
  * - those differ per schema, so there is nothing to share.
  */
 var commonSchemaFields = {
-  render: FieldRender,
   preview: zod.z.literal(true).optional(),
   // Whether the schema declares a `.validate()`. The function cannot serialize,
   // so this flag is what tells the Studio to run the custom validators on the
@@ -1068,6 +1068,7 @@ var SerializedObjectSchema = zod.z.lazy(function () {
 });
 var SerializedArraySchema = zod.z.lazy(function () {
   return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("array"),
     item: SerializedSchema,
     opt: zod.z["boolean"]()
@@ -1160,6 +1161,7 @@ var SerializedRichTextSchema = zod.z.object(getSitemapTree._objectSpread2(getSit
 }));
 var SerializedRecordSchema = zod.z.lazy(function () {
   return zod.z.preprocess(readLegacyDirectoryAsDir, zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("record"),
     item: SerializedSchema,
     opt: zod.z["boolean"](),
@@ -1176,6 +1178,7 @@ var SerializedRecordSchema = zod.z.lazy(function () {
 });
 var SerializedKeyOfSchema = zod.z.lazy(function () {
   return zod.z.object(getSitemapTree._objectSpread2(getSitemapTree._objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: zod.z.literal("keyOf"),
     path: SourcePath,
     schema: zod.z.union([zod.z.object({
@@ -1235,7 +1238,6 @@ var SerializedCodeSchema = zod.z.object(getSitemapTree._objectSpread2(getSitemap
 }));
 var SerializedLocaleSchema = zod.z.object({
   type: zod.z.literal("locale"),
-  render: FieldRender,
   preview: zod.z.literal(true).optional(),
   opt: zod.z["boolean"](),
   customValidate: zod.z["boolean"]().optional(),
@@ -1261,7 +1263,7 @@ var SerializedRouteSchema = zod.z.object(getSitemapTree._objectSpread2(getSitema
 
 // 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
+// settings schemas. `s.settings()` never writes preview/customValidate
 // (see core/src/schema/settings.ts), but they are accepted here because they
 // are part of the declared type.
 var SerializedSettingsSchema = zod.z.lazy(function () {
@@ -1287,7 +1289,6 @@ var SerializedSettingsSchema = zod.z.lazy(function () {
  */
 var SerializedValViewSchema = zod.z.object({
   type: zod.z.literal("view"),
-  render: FieldRender.optional(),
   moduleFilePath: ModuleFilePath$1,
   opt: zod.z.literal(false),
   readonly: zod.z["boolean"]().optional(),
@@ -2027,6 +2028,14 @@ var Api = {
            * highest version. Optional, for the same reason `headPatchId` is.
            */
           headVersion: zod.z.number().optional(),
+          /**
+           * Every group on the branch and which listed patches it holds,
+           * read with the list and `headVersion`. What a Studio's view of
+           * the groups is taken from, so a stage or an unstage made in
+           * another browser reaches it with the next stat. Absent where
+           * the content service has no groups.
+           */
+          patchGroups: zod.z.array(PatchGroup).optional(),
           commits: zod.z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2426,7 +2435,12 @@ var Api = {
     PUT: {
       req: {
         body: zod.z.object({
-          patchGroupId: zod.z.string(),
+          /**
+           * The group to stage into. Absent means the caller's open group on
+           * the branch, created if there is none — which is what the Studio
+           * sends, so a stage never has to wait for a group to exist.
+           */
+          patchGroupId: zod.z.string().optional(),
           /** What the user asked to stage. */
           patchIds: zod.z.array(PatchId),
           /*
@@ -2464,15 +2478,23 @@ var Api = {
       }), zod.z.object({
         status: zod.z.literal(200),
         json: zod.z.object({
-          patchGroupId: zod.z.string(),
-          patchIds: zod.z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: zod.z.string().nullable(),
+          patchIds: zod.z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     },
     DELETE: {
       req: {
         body: zod.z.object({
-          patchGroupId: zod.z.string(),
+          /** See the PUT. Absent with no open group is a no-op. */
+          patchGroupId: zod.z.string().optional(),
           /** What the user asked to unstage. */
           patchIds: zod.z.array(PatchId),
           /** What has to go with it: everything built on top of it. */
@@ -2497,8 +2519,15 @@ var Api = {
       }), zod.z.object({
         status: zod.z.literal(200),
         json: zod.z.object({
-          patchGroupId: zod.z.string(),
-          patchIds: zod.z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: zod.z.string().nullable(),
+          patchIds: zod.z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     }

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

@@ -980,7 +980,8 @@ var _excluded = ["directory"];
 
 // A render is static config, so unlike a `preview` it travels WHOLE — this
 // is the field the editor reads the layout from. See `core/src/render.ts`.
-// Every field can carry `{ as: "inline" }`, and that is all a render says.
+// Only array, record and keyOf carry one, and `{ as: "inline" }` is all it
+// says. A stale `render` on any other schema is stripped here, harmlessly.
 // NB: these z.objects STRIP unknown keys, so a render variant that is not
 // declared here is silently dropped in transit — add it here when it is added
 // to `render.ts`.
@@ -1002,7 +1003,6 @@ var FieldRender = InlineRender.optional();
  * - those differ per schema, so there is nothing to share.
  */
 var commonSchemaFields = {
-  render: FieldRender,
   preview: z.literal(true).optional(),
   // Whether the schema declares a `.validate()`. The function cannot serialize,
   // so this flag is what tells the Studio to run the custom validators on the
@@ -1061,6 +1061,7 @@ var SerializedObjectSchema = z.lazy(function () {
 });
 var SerializedArraySchema = z.lazy(function () {
   return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: z.literal("array"),
     item: SerializedSchema,
     opt: z["boolean"]()
@@ -1153,6 +1154,7 @@ var SerializedRichTextSchema = z.object(_objectSpread2(_objectSpread2({}, common
 }));
 var SerializedRecordSchema = z.lazy(function () {
   return z.preprocess(readLegacyDirectoryAsDir, z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: z.literal("record"),
     item: SerializedSchema,
     opt: z["boolean"](),
@@ -1169,6 +1171,7 @@ var SerializedRecordSchema = z.lazy(function () {
 });
 var SerializedKeyOfSchema = z.lazy(function () {
   return z.object(_objectSpread2(_objectSpread2({}, commonSchemaFields), {}, {
+    render: FieldRender,
     type: z.literal("keyOf"),
     path: SourcePath,
     schema: z.union([z.object({
@@ -1228,7 +1231,6 @@ var SerializedCodeSchema = z.object(_objectSpread2(_objectSpread2({}, commonSche
 }));
 var SerializedLocaleSchema = z.object({
   type: z.literal("locale"),
-  render: FieldRender,
   preview: z.literal(true).optional(),
   opt: z["boolean"](),
   customValidate: z["boolean"]().optional(),
@@ -1254,7 +1256,7 @@ var SerializedRouteSchema = z.object(_objectSpread2(_objectSpread2({}, commonSch
 
 // 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
+// settings schemas. `s.settings()` never writes 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 () {
@@ -1280,7 +1282,6 @@ var SerializedSettingsSchema = z.lazy(function () {
  */
 var SerializedValViewSchema = z.object({
   type: z.literal("view"),
-  render: FieldRender.optional(),
   moduleFilePath: ModuleFilePath$1,
   opt: z.literal(false),
   readonly: z["boolean"]().optional(),
@@ -2020,6 +2021,14 @@ var Api = {
            * highest version. Optional, for the same reason `headPatchId` is.
            */
           headVersion: z.number().optional(),
+          /**
+           * Every group on the branch and which listed patches it holds,
+           * read with the list and `headVersion`. What a Studio's view of
+           * the groups is taken from, so a stage or an unstage made in
+           * another browser reaches it with the next stat. Absent where
+           * the content service has no groups.
+           */
+          patchGroups: z.array(PatchGroup).optional(),
           commits: z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2419,7 +2428,12 @@ var Api = {
     PUT: {
       req: {
         body: z.object({
-          patchGroupId: z.string(),
+          /**
+           * The group to stage into. Absent means the caller's open group on
+           * the branch, created if there is none — which is what the Studio
+           * sends, so a stage never has to wait for a group to exist.
+           */
+          patchGroupId: z.string().optional(),
           /** What the user asked to stage. */
           patchIds: z.array(PatchId),
           /*
@@ -2457,15 +2471,23 @@ var Api = {
       }), z.object({
         status: z.literal(200),
         json: z.object({
-          patchGroupId: z.string(),
-          patchIds: z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: z.string().nullable(),
+          patchIds: z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: z.number().optional()
         })
       })])
     },
     DELETE: {
       req: {
         body: z.object({
-          patchGroupId: z.string(),
+          /** See the PUT. Absent with no open group is a no-op. */
+          patchGroupId: z.string().optional(),
           /** What the user asked to unstage. */
           patchIds: z.array(PatchId),
           /** What has to go with it: everything built on top of it. */
@@ -2490,8 +2512,15 @@ var Api = {
       }), z.object({
         status: z.literal(200),
         json: z.object({
-          patchGroupId: z.string(),
-          patchIds: z.array(PatchId)
+          /** `null` for an unstage when the caller has no open group. */
+          patchGroupId: z.string().nullable(),
+          patchIds: z.array(PatchId),
+          /**
+           * The chain version the change committed at. The client keeps its
+           * own view of the change until a stat at least this new shows it.
+           * Absent from a content service that predates it.
+           */
+          headVersion: z.number().optional()
         })
       })])
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.138.4",
+  "version": "0.139.1",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -37,7 +37,7 @@
     "flexsearch": "^0.8.212",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.138.2"
+    "@valbuild/core": "0.139.1"
   },
   "files": [
     "CHANGELOG.md",