@valbuild/shared 0.139.0 → 0.140.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @valbuild/shared
 
+## 0.140.0
+
+### Minor Changes
+
+- [#769](https://github.com/valbuild/val/pull/769) [`cb93874`](https://github.com/valbuild/val/commit/cb938748aec15fd0ac3814c1696a2dd78ad63c27) Thanks [@freekh](https://github.com/freekh)! - The project name in the Studio's top bar is now a project switcher, for projects connected to Val Build. It shows the project you are in, the projects you pinned and the five you opened most recently, and searches every project in your organisations. Choosing one opens its Studio.
+
+  The top bar also gets a **Share** button (an icon on a phone). It shows who is in the project's organisation. Owners can create invite links for a role (each works once and expires after 7 days), see and revoke pending links, and change members' roles. Everyone else can see the members and which owners to ask.
+
+  The assistant can be set up from the Studio too. Settings › Assistant shows the AI key this project runs on and whether it works. From there you can add a key, update it, remove it, or choose one that already exists: the organisation's, your own, or another project's. The assistant's empty state offers the same when no key is set up. Every key is checked with the provider before it is saved, and once a key is saved the assistant turns on without a reload.
+
+  The panels are served by Val's content server (`content.val.build/wc/v1/project-switcher.js`, `members.js` and `ai-setup.js`), beside the API they read and write, so they can improve without a Val release. The Studio draws the project name and the Share button itself, and loads the switcher and Share panels only when the button is first hovered or clicked, so opening the Studio fetches nothing extra. If a panel cannot load, for example offline or under a strict Content Security Policy, the click opens the same page in Val Build instead, and the AI setup is a link to the project's AI keys there. If your app sets a CSP, allow `script-src https://content.val.build` to get them.
+
+  They reach Val Build through a new route on your app's Val server, `/api/val/admin/proxy/*`, which adds the editor's existing Val Build session. That route forwards only to the Studio API on Val's content server (`/v1/studio/*` on `VAL_CONTENT_URL`, `https://content.val.build` by default), and only with the `x-val-studio` header that a cross-site request cannot send.
+
+  In local development they appear once you have run `val login`, and use that login. Without one the Studio keeps the plain project name, as before; it does not load them just to say you are not logged in.
+
+## 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

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

@@ -1,6 +1,12 @@
 import { z } from "zod";
 import { type ModuleFilePath } from "@valbuild/core";
 declare const ModuleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+/**
+ * The header a request to `/admin/proxy` must carry. A cross-site form or
+ * `<img>` cannot set a custom header, so without it the proxy cannot be driven
+ * with the editor's cookie from another site.
+ */
+export declare const VAL_STUDIO_HEADER = "x-val-studio";
 /**
  * A patch group: the set of patches one user has chosen to publish.
  *
@@ -442,6 +448,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 +876,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 +907,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 +947,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>]>;
         };
@@ -1966,6 +1981,95 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    "/admin/status": {
+        GET: {
+            req: {
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    connected: z.ZodBoolean;
+                    signIn: z.ZodOptional<z.ZodEnum<{
+                        "val-login": "val-login";
+                        studio: "studio";
+                    }>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        };
+    };
+    "/admin/proxy": {
+        GET: {
+            req: {
+                path: z.ZodString;
+                rawQuery: z.ZodString;
+                headers: {
+                    "x-val-studio": z.ZodOptional<z.ZodString>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                body: z.ZodUnknown;
+            };
+            res: z.ZodObject<{
+                status: z.ZodUnion<readonly [z.ZodLiteral<200>, z.ZodLiteral<400>, z.ZodLiteral<401>, z.ZodLiteral<403>, z.ZodLiteral<404>, z.ZodLiteral<500>]>;
+                json: z.ZodUnknown;
+            }, z.core.$strip>;
+        };
+        POST: {
+            req: {
+                path: z.ZodString;
+                rawQuery: z.ZodString;
+                headers: {
+                    "x-val-studio": z.ZodOptional<z.ZodString>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                body: z.ZodUnknown;
+            };
+            res: z.ZodObject<{
+                status: z.ZodUnion<readonly [z.ZodLiteral<200>, z.ZodLiteral<400>, z.ZodLiteral<401>, z.ZodLiteral<403>, z.ZodLiteral<404>, z.ZodLiteral<500>]>;
+                json: z.ZodUnknown;
+            }, z.core.$strip>;
+        };
+        PUT: {
+            req: {
+                path: z.ZodString;
+                rawQuery: z.ZodString;
+                headers: {
+                    "x-val-studio": z.ZodOptional<z.ZodString>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                body: z.ZodUnknown;
+            };
+            res: z.ZodObject<{
+                status: z.ZodUnion<readonly [z.ZodLiteral<200>, z.ZodLiteral<400>, z.ZodLiteral<401>, z.ZodLiteral<403>, z.ZodLiteral<404>, z.ZodLiteral<500>]>;
+                json: z.ZodUnknown;
+            }, z.core.$strip>;
+        };
+        DELETE: {
+            req: {
+                path: z.ZodString;
+                rawQuery: z.ZodString;
+                headers: {
+                    "x-val-studio": z.ZodOptional<z.ZodString>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                body: z.ZodUnknown;
+            };
+            res: z.ZodObject<{
+                status: z.ZodUnion<readonly [z.ZodLiteral<200>, z.ZodLiteral<400>, z.ZodLiteral<401>, z.ZodLiteral<403>, z.ZodLiteral<404>, z.ZodLiteral<500>]>;
+                json: z.ZodUnknown;
+            }, z.core.$strip>;
+        };
+    };
 };
 /**
  * Extracts the keys of an object where the value is not undefined.
@@ -1999,6 +2103,16 @@ export type ApiEndpoint = {
         body?: z.ZodTypeAny;
         query?: Record<string, z.ZodSchema<ValidQueryParamTypes, string[] | undefined>>;
         cookies?: Record<string, z.ZodSchema<string | undefined>>;
+        /**
+         * Request headers, by lower-case name, parsed the way `cookies` are.
+         * Absent ones are `undefined`.
+         */
+        headers?: Record<string, z.ZodSchema<string | undefined>>;
+        /**
+         * The query string exactly as sent (`?a=1&b=2`, or `""`), for a route that
+         * forwards it rather than reading it. `query` is for routes that read it.
+         */
+        rawQuery?: z.ZodString;
     };
     res: z.ZodSchema<{
         status: number;
@@ -2027,6 +2141,10 @@ export type ServerOf<Api extends ApiGuard> = {
             cookies: Api[Route][Method]["req"]["cookies"] extends Record<string, z.ZodSchema<string | undefined>> ? {
                 [key in keyof Api[Route][Method]["req"]["cookies"]]: z.infer<Api[Route][Method]["req"]["cookies"][key]>;
             } : undefined;
+            headers: Api[Route][Method]["req"]["headers"] extends Record<string, z.ZodSchema<string | undefined>> ? {
+                [key in keyof Api[Route][Method]["req"]["headers"]]: z.infer<Api[Route][Method]["req"]["headers"][key]>;
+            } : undefined;
+            rawQuery: Api[Route][Method]["req"]["rawQuery"] extends z.ZodString ? string : undefined;
         }>) => Promise<z.infer<Api[Route][Method]["res"]>> : never;
     };
 };

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

@@ -1504,6 +1504,35 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * The header a request to `/admin/proxy` must carry. A cross-site form or
+ * `<img>` cannot set a custom header, so without it the proxy cannot be driven
+ * with the editor's cookie from another site.
+ */
+var VAL_STUDIO_HEADER = "x-val-studio";
+
+/**
+ * What Val Build answered, mapped onto the statuses this server speaks: a
+ * `code` in the JSON is what the web components act on, so it is passed
+ * through untouched.
+ */
+var AdminProxyResponse = zod.z.object({
+  status: zod.z.union([zod.z.literal(200), zod.z.literal(400), zod.z.literal(401), zod.z.literal(403), zod.z.literal(404), zod.z.literal(500)]),
+  json: zod.z.unknown()
+});
+function adminProxyEndpoint() {
+  return {
+    req: {
+      path: zod.z.string(),
+      rawQuery: zod.z.string(),
+      headers: getSitemapTree._defineProperty({}, VAL_STUDIO_HEADER, zod.z.string().optional()),
+      cookies: getSitemapTree._defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional()),
+      body: zod.z.unknown()
+    },
+    res: AdminProxyResponse
+  };
+}
+
 /**
  * What answered when one URL was opened.
  *
@@ -2028,6 +2057,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.
@@ -2427,7 +2464,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),
           /*
@@ -2465,15 +2507,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. */
@@ -2498,8 +2548,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()
         })
       })])
     }
@@ -3418,6 +3475,50 @@ var Api = {
         json: GenericError
       })])
     }
+  },
+  /*
+   * Val Build, on the editor's behalf, for the web components the Studio
+   * mounts from admin.val.build (`<val-project-switcher>` and the ones after
+   * it). `/admin/proxy/projects/overview?current=…` is
+   * `{valBuildUrl}/api/studio/v1/projects/overview?current=…`, with the
+   * editor's token from the session cookie: the component cannot send that
+   * token itself, because it is in an httpOnly cookie only this server reads.
+   *
+   * A pipe, deliberately: the path, the query and the JSON body go through as
+   * they are, so a new component or endpoint on Val Build needs no Val
+   * release. What it does NOT pass through is anything that would let it be
+   * aimed elsewhere — see `adminProxy.ts`.
+   */
+  /*
+   * Whether this Studio has a Val Build credential for the editor: a session,
+   * or in local development a `val login`. The Studio asks before it loads a
+   * web component, so a developer who never logged in sees the plain project
+   * name rather than a component explaining that they are not logged in.
+   */
+  "/admin/status": {
+    GET: {
+      req: {
+        cookies: getSitemapTree._defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional())
+      },
+      res: zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          connected: zod.z["boolean"](),
+          /**
+           * `val-login` on a developer's own checkout, `studio` anywhere the
+           * Studio's sign-in is the way in. Optional: an older server does
+           * not send it.
+           */
+          signIn: zod.z["enum"](["val-login", "studio"]).optional()
+        })
+      })
+    }
+  },
+  "/admin/proxy": {
+    GET: adminProxyEndpoint(),
+    POST: adminProxyEndpoint(),
+    PUT: adminProxyEndpoint(),
+    DELETE: adminProxyEndpoint()
   }
 };
 
@@ -7744,6 +7845,7 @@ exports.VAL_ENABLE_COOKIE_NAME = VAL_ENABLE_COOKIE_NAME;
 exports.VAL_GREEN_RAMP = VAL_GREEN_RAMP;
 exports.VAL_SESSION_COOKIE = VAL_SESSION_COOKIE;
 exports.VAL_STATE_COOKIE = VAL_STATE_COOKIE;
+exports.VAL_STUDIO_HEADER = VAL_STUDIO_HEADER;
 exports.ValCommit = ValCommit;
 exports.ValDeployment = ValDeployment;
 exports.accentRamp = accentRamp;

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

@@ -1504,6 +1504,35 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * The header a request to `/admin/proxy` must carry. A cross-site form or
+ * `<img>` cannot set a custom header, so without it the proxy cannot be driven
+ * with the editor's cookie from another site.
+ */
+var VAL_STUDIO_HEADER = "x-val-studio";
+
+/**
+ * What Val Build answered, mapped onto the statuses this server speaks: a
+ * `code` in the JSON is what the web components act on, so it is passed
+ * through untouched.
+ */
+var AdminProxyResponse = zod.z.object({
+  status: zod.z.union([zod.z.literal(200), zod.z.literal(400), zod.z.literal(401), zod.z.literal(403), zod.z.literal(404), zod.z.literal(500)]),
+  json: zod.z.unknown()
+});
+function adminProxyEndpoint() {
+  return {
+    req: {
+      path: zod.z.string(),
+      rawQuery: zod.z.string(),
+      headers: getSitemapTree._defineProperty({}, VAL_STUDIO_HEADER, zod.z.string().optional()),
+      cookies: getSitemapTree._defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional()),
+      body: zod.z.unknown()
+    },
+    res: AdminProxyResponse
+  };
+}
+
 /**
  * What answered when one URL was opened.
  *
@@ -2028,6 +2057,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.
@@ -2427,7 +2464,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),
           /*
@@ -2465,15 +2507,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. */
@@ -2498,8 +2548,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()
         })
       })])
     }
@@ -3418,6 +3475,50 @@ var Api = {
         json: GenericError
       })])
     }
+  },
+  /*
+   * Val Build, on the editor's behalf, for the web components the Studio
+   * mounts from admin.val.build (`<val-project-switcher>` and the ones after
+   * it). `/admin/proxy/projects/overview?current=…` is
+   * `{valBuildUrl}/api/studio/v1/projects/overview?current=…`, with the
+   * editor's token from the session cookie: the component cannot send that
+   * token itself, because it is in an httpOnly cookie only this server reads.
+   *
+   * A pipe, deliberately: the path, the query and the JSON body go through as
+   * they are, so a new component or endpoint on Val Build needs no Val
+   * release. What it does NOT pass through is anything that would let it be
+   * aimed elsewhere — see `adminProxy.ts`.
+   */
+  /*
+   * Whether this Studio has a Val Build credential for the editor: a session,
+   * or in local development a `val login`. The Studio asks before it loads a
+   * web component, so a developer who never logged in sees the plain project
+   * name rather than a component explaining that they are not logged in.
+   */
+  "/admin/status": {
+    GET: {
+      req: {
+        cookies: getSitemapTree._defineProperty({}, VAL_SESSION_COOKIE, zod.z.string().optional())
+      },
+      res: zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          connected: zod.z["boolean"](),
+          /**
+           * `val-login` on a developer's own checkout, `studio` anywhere the
+           * Studio's sign-in is the way in. Optional: an older server does
+           * not send it.
+           */
+          signIn: zod.z["enum"](["val-login", "studio"]).optional()
+        })
+      })
+    }
+  },
+  "/admin/proxy": {
+    GET: adminProxyEndpoint(),
+    POST: adminProxyEndpoint(),
+    PUT: adminProxyEndpoint(),
+    DELETE: adminProxyEndpoint()
   }
 };
 
@@ -7744,6 +7845,7 @@ exports.VAL_ENABLE_COOKIE_NAME = VAL_ENABLE_COOKIE_NAME;
 exports.VAL_GREEN_RAMP = VAL_GREEN_RAMP;
 exports.VAL_SESSION_COOKIE = VAL_SESSION_COOKIE;
 exports.VAL_STATE_COOKIE = VAL_STATE_COOKIE;
+exports.VAL_STUDIO_HEADER = VAL_STUDIO_HEADER;
 exports.ValCommit = ValCommit;
 exports.ValDeployment = ValDeployment;
 exports.accentRamp = accentRamp;

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

@@ -1497,6 +1497,35 @@ var GenericError = z.object({
   message: z.string()
 });
 
+/**
+ * The header a request to `/admin/proxy` must carry. A cross-site form or
+ * `<img>` cannot set a custom header, so without it the proxy cannot be driven
+ * with the editor's cookie from another site.
+ */
+var VAL_STUDIO_HEADER = "x-val-studio";
+
+/**
+ * What Val Build answered, mapped onto the statuses this server speaks: a
+ * `code` in the JSON is what the web components act on, so it is passed
+ * through untouched.
+ */
+var AdminProxyResponse = z.object({
+  status: z.union([z.literal(200), z.literal(400), z.literal(401), z.literal(403), z.literal(404), z.literal(500)]),
+  json: z.unknown()
+});
+function adminProxyEndpoint() {
+  return {
+    req: {
+      path: z.string(),
+      rawQuery: z.string(),
+      headers: _defineProperty({}, VAL_STUDIO_HEADER, z.string().optional()),
+      cookies: _defineProperty({}, VAL_SESSION_COOKIE, z.string().optional()),
+      body: z.unknown()
+    },
+    res: AdminProxyResponse
+  };
+}
+
 /**
  * What answered when one URL was opened.
  *
@@ -2021,6 +2050,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.
@@ -2420,7 +2457,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),
           /*
@@ -2458,15 +2500,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. */
@@ -2491,8 +2541,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()
         })
       })])
     }
@@ -3411,6 +3468,50 @@ var Api = {
         json: GenericError
       })])
     }
+  },
+  /*
+   * Val Build, on the editor's behalf, for the web components the Studio
+   * mounts from admin.val.build (`<val-project-switcher>` and the ones after
+   * it). `/admin/proxy/projects/overview?current=…` is
+   * `{valBuildUrl}/api/studio/v1/projects/overview?current=…`, with the
+   * editor's token from the session cookie: the component cannot send that
+   * token itself, because it is in an httpOnly cookie only this server reads.
+   *
+   * A pipe, deliberately: the path, the query and the JSON body go through as
+   * they are, so a new component or endpoint on Val Build needs no Val
+   * release. What it does NOT pass through is anything that would let it be
+   * aimed elsewhere — see `adminProxy.ts`.
+   */
+  /*
+   * Whether this Studio has a Val Build credential for the editor: a session,
+   * or in local development a `val login`. The Studio asks before it loads a
+   * web component, so a developer who never logged in sees the plain project
+   * name rather than a component explaining that they are not logged in.
+   */
+  "/admin/status": {
+    GET: {
+      req: {
+        cookies: _defineProperty({}, VAL_SESSION_COOKIE, z.string().optional())
+      },
+      res: z.object({
+        status: z.literal(200),
+        json: z.object({
+          connected: z["boolean"](),
+          /**
+           * `val-login` on a developer's own checkout, `studio` anywhere the
+           * Studio's sign-in is the way in. Optional: an older server does
+           * not send it.
+           */
+          signIn: z["enum"](["val-login", "studio"]).optional()
+        })
+      })
+    }
+  },
+  "/admin/proxy": {
+    GET: adminProxyEndpoint(),
+    POST: adminProxyEndpoint(),
+    PUT: adminProxyEndpoint(),
+    DELETE: adminProxyEndpoint()
   }
 };
 
@@ -7648,4 +7749,4 @@ function parse(schema, body, call) {
   return parsed.data;
 }
 
-export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, ValCommit, ValDeployment, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseCancel, parseDeclare, parseDiscard, parseJob, parseNewestCiRun, parsePress, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseRenew, parseRequestStatus, parseStatus, parseUpdateTarget, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_STUDIO_HEADER, ValCommit, ValDeployment, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseCancel, parseDeclare, parseDiscard, parseJob, parseNewestCiRun, parsePress, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseRenew, parseRequestStatus, parseStatus, parseUpdateTarget, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.139.0",
+  "version": "0.140.0",
   "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.139.0"
+    "@valbuild/core": "0.139.1"
   },
   "files": [
     "CHANGELOG.md",