@valbuild/shared 0.118.0 → 0.121.0

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # @valbuild/shared
 
+## 0.121.0
+
+### Minor Changes
+
+- [#464](https://github.com/valbuild/val/pull/464) [`2bcc6fd`](https://github.com/valbuild/val/commit/2bcc6fdff8d668123e07e3c5e81ac6fa1436e47b) Thanks [@freekh](https://github.com/freekh)! - Add staging and unstaging of pending changes, so one person can publish a small fix without shipping somebody else's unfinished work.
+
+  A **patch group** is the set of patches one user has chosen to publish. It is not a patch _set_: a patch set is computed from the schema and says which patches must move together, while a patch group is curated and says which ones you want live.
+
+  A group holds its owner's own work plus whatever the closure entangled with it — not everything pending. **So Publish changes meaning on a shared branch: it ships your changes and what they depend on, instead of everything anybody has pending.** That is the feature. Unstaging goes further: hold one of your own changes back and it leaves both your preview and your publish, while still existing for everyone else.
+
+  The rule relating the two is that for every group and every patch set, the group's members within that patch set must form a prefix in patch-chain order. Staging a change therefore pulls in whatever preceded it in the same patch set; unstaging drops whatever was built on top of it. The compare view names what a toggle moves, and whose it is, rather than quietly enlarging or shrinking a publish.
+
+  Editing inside a region you are holding back is allowed, and the patches you were holding are loaded back in rather than the edit being refused. An earlier design made such a region read-only until it was staged again, because an author picks an array index while looking at their own view — so re-staging patches afterwards can shift the content under the path they just chose, and their edit lands on the wrong element cleanly, with every invariant intact and only the content wrong. That guard is not what ships. It is a rare shape in practice, since two people's edits mostly land in different routes, and refusing an edit for a reason the author cannot see is a worse everyday experience than the case it prevents. Instead the real result is shown immediately: the widened set is what the editor renders and what the compare view lists.
+
+  Also fixes a pre-existing bug in patch set grouping: patch set paths were compared with a raw string prefix test, and nothing terminates a path segment, so `?foobar/title` matched `?foo`. Deleting record key `foo` and retitling record key `foobar` were treated as one inseparable change. Previously that over-grouped two unrelated edits in the review screen; with staging it would have meant publishing a deletion nobody asked for.
+
+  The `/patches` routes gain optional patch group fields and `/patch-groups/~/patches` is new. This needs a content API that has patch groups. Filesystem mode keeps the group in the client, since it has a single author and already sends an explicit patch id list when publishing.
+
+  When a save pulls other people's changes in, you are told: a toast names how many and whose. There is no undo, because your edit was written against the view those changes produce and now depends on them — the compare view shows the widened set.
+
+  Two other things keep a session honest about a shared branch. `/stat` now says which pending changes have already been published, so another author's publish stops looking pending in your Studio the moment it lands rather than when the site redeploys. And Publish refuses, without writing anything, if somebody published while you were reviewing — the review screen you acted on described a branch that has since moved.
+
+  Two things this does **not** do yet, both of which need the group annotation to refresh on its own rather than only inside a fetch for missing patch ids:
+
+  - a stage or unstage in one tab does not reach another tab;
+  - if persisting a stage fails, the local view keeps it until the page is reloaded.
+
+  `docs/independent-publish/DESIGN.md` describes the model and lists what is still a judgement call.
+
+- [#605](https://github.com/valbuild/val/pull/605) [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79) Thanks [@freekh](https://github.com/freekh)! - `s.settings()`: the project's settings, as content.
+
+  A settings module is one per project, at the root of the content tree:
+
+  ```typescript
+  // settings.val.ts
+  export default c.define("/settings.val.ts", s.settings(), {});
+  ```
+
+  Register it in `val.modules.ts` like any other module, and it shows up in the
+  Studio under the cog at the foot of the left rail. Everything in it is content:
+  it is edited as a draft, it appears in the publish diff, and it is the same for
+  everyone working on the project.
+
+  Every key is optional, at every level, so `{}` is a complete settings module —
+  and stays one as sections are added. What it holds today is the assistant:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    assistant: {
+      enabled: true,
+      context: "A CMS for developers, run by a team of four in Oslo.",
+      tone: "Plain and direct. British English, sentence case in headings.",
+    },
+  });
+  ```
+
+  `context` is background the assistant would otherwise guess at; `tone` is how it
+  should write when it writes content. Both are sent with every message it makes.
+
+  `enabled` decides whether editors have an assistant, and it has **three** states
+  rather than two:
+
+  - `true` — they do.
+  - `false` — they do not, and every trace of it goes: no button in the top bar,
+    no row in the quick actions, no panel, nothing sent.
+  - unset — nobody has decided. The assistant is still **shown**, and asks to be
+    turned on before it is used. Hiding an assistant nobody has decided about
+    means nobody discovers it; quietly enabling one means a project starts sending
+    its content to a model because it did not know to say no.
+
+  A project with no settings module at all has an assistant, as before: there is
+  nowhere to record a decision, and nowhere for the prompt to write the answer.
+
+  **Breaking: `ai.chat` is gone from `val.config.ts`.** Whether the assistant is
+  available is a decision about the project's content, made by the people who edit
+  it, so it moved to settings — turning the chat on used to take a developer, a
+  deploy and a code review of a boolean. Remove the whole block:
+
+  ```diff
+   const { s, c, val, config } = initVal({
+  -  ai: {
+  -    chat: {
+  -      experimental: { enable: true },
+  -      suggestions: ["Summarize", "Fix typos at this page"],
+  -      title: "Ask me anything",
+  -      description: "Val can answer questions about the content.",
+  -    },
+  -  },
+   });
+  ```
+
+  `experimental.enable` becomes `assistant.enabled` in the settings module.
+  `suggestions`, `title` and `description` are removed with nothing replacing
+  them: the assistant now opens with its own copy. A project that had the chat
+  enabled and wants it to stay on for everyone should write
+  `assistant: { enabled: true }` — otherwise editors are offered it and asked.
+
+  `ai.commitMessages` stays in `val.config.ts`, and is unaffected.
+
+  Two settings modules, or one in a subdirectory, is a module error: the dev
+  server refuses to serve sources, `npx val validate` reports it against the file,
+  and the Studio says so rather than picking one.
+
+### Patch Changes
+
+- Updated dependencies [[`2bcbee1`](https://github.com/valbuild/val/commit/2bcbee1be682c2bbd5b7bc7d152ddd4204162fd2), [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79)]:
+  - @valbuild/core@0.121.0
+
+## 0.120.0
+
+### Minor Changes
+
+- [#589](https://github.com/valbuild/val/pull/589) [`c2d3c0e`](https://github.com/valbuild/val/commit/c2d3c0e6c2010c0a94c725d9dbaa618998773e8a) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.richtext()` options are flat.
+
+  The `style`, `block` and `inline` groups are gone — every option is a key of its
+  own. The names are unchanged, so updating a schema is only a matter of removing
+  the wrappers:
+
+  ```ts
+  // before
+  s.richtext({
+    style: { bold: true, italic: true },
+    block: { h1: true, ul: true },
+    inline: { a: true, img: s.image() },
+  });
+
+  // after
+  s.richtext({
+    bold: true,
+    italic: true,
+    h1: true,
+    ul: true,
+    a: true,
+    img: s.image(),
+  });
+  ```
+
+  The groups never carried any meaning the option names did not already have, and
+  they cost something real: an option name and its `ValRichText` theme key were
+  spelled differently (`block.h1` vs `theme.h1`), so the type that keeps a theme
+  exhaustive had to restate all thirteen options by hand. It is now a mapped type
+  over the options themselves — which also fixes an inconsistency in it: enabling
+  links with a schema (`a: s.route()`) rather than `a: true` now requires an `a`
+  key in the theme, the way `img` always has.
+
+  `ValRichText` themes were already flat and are unchanged. The serialized schema
+  that the server sends the Studio is flat too, so a project must not mix
+  `@valbuild/*` versions across this release.
+
+### Patch Changes
+
+- Updated dependencies [[`c2d3c0e`](https://github.com/valbuild/val/commit/c2d3c0e6c2010c0a94c725d9dbaa618998773e8a)]:
+  - @valbuild/core@0.120.0
+
 ## 0.118.0
 
 ### Minor Changes

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

@@ -1,6 +1,21 @@
 import { z } from "zod";
 import { type ModuleFilePath } from "@valbuild/core";
 declare const ModuleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+/**
+ * A patch group: the set of patches one user has chosen to publish.
+ *
+ * Not a patch *set* — a patch set is computed from the schema and says which
+ * patches must move together; a patch group is curated and says which ones this
+ * user wants live. See `docs/independent-publish/PLAN.md`.
+ */
+export declare const PatchGroup: 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>;
+export type PatchGroupT = z.infer<typeof PatchGroup>;
 declare const cookies: z.ZodUnion<readonly [z.ZodLiteral<"val_session">, z.ZodLiteral<"val_enable">, z.ZodLiteral<"val_state">]>;
 type Cookies = z.infer<typeof cookies>;
 declare const enableCookieValue: z.ZodObject<{
@@ -430,6 +445,8 @@ export declare const Api: {
                     schemaSha: z.ZodString;
                     sourcesSha: z.ZodString;
                     patches: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    appliedPatches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    headCommitSha: z.ZodOptional<z.ZodString>;
                     removed: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
                         reason: z.ZodString;
@@ -455,6 +472,8 @@ export declare const Api: {
                     sourcesSha: z.ZodString;
                     commitSha: z.ZodString;
                     patches: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    appliedPatches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    headCommitSha: z.ZodOptional<z.ZodString>;
                     commits: z.ZodArray<z.ZodObject<{
                         commitSha: z.ZodString;
                         clientCommitSha: z.ZodString;
@@ -551,6 +570,9 @@ export declare const Api: {
                 query: {
                     id: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
                 };
+                body: z.ZodOptional<z.ZodObject<{
+                    unstagePatchIds: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                }, z.core.$strip>>;
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
                 };
@@ -593,6 +615,8 @@ export declare const Api: {
                         patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
                         patch: z.ZodAny;
                     }, z.core.$strip>>;
+                    patchGroupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    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>;
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -631,6 +655,7 @@ export declare const Api: {
                         type: z.ZodLiteral<"patch">;
                         patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
                     }, z.core.$strip>]>;
+                    patchGroupId: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
@@ -639,6 +664,15 @@ export declare const Api: {
                 query: {
                     patch_id: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                     exclude_patch_ops: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
+                    /**
+                     * Include the patch group annotation in the answer.
+                     *
+                     * Off by default because the client CHUNKS this request — a long
+                     * chain is several round trips — and the groups are a property of the
+                     * branch, identical in every chunk. Asking on each one is N identical
+                     * lookups against the content API to learn the same thing.
+                     */
+                    include_patch_groups: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
                 };
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -712,7 +746,15 @@ export declare const Api: {
                         appliedAt: z.ZodNullable<z.ZodObject<{
                             commitSha: z.ZodString;
                         }, z.core.$strip>>;
+                        patchGroupIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     }, z.core.$strip>>;
+                    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>>>;
                     baseSha: z.ZodString;
                     error: z.ZodOptional<z.ZodObject<{
                         message: z.ZodString;
@@ -724,6 +766,86 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    "/patch-groups/~/patches": {
+        PUT: {
+            req: {
+                body: z.ZodObject<{
+                    patchGroupId: 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>;
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<403>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<409>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    patchGroupId: 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>;
+            }, z.core.$strip>]>;
+        };
+        DELETE: {
+            req: {
+                body: z.ZodObject<{
+                    patchGroupId: 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>;
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<403>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<409>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    patchGroupId: 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>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/schema": {
         GET: {
             req: {
@@ -771,6 +893,33 @@ export declare const Api: {
                     validate_binary_files: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
                     exclude_patches: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
                     apply_patches: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
+                    /**
+                     * Apply ONLY these patches, rather than everything pending.
+                     *
+                     * This is what makes a draft-mode render match the caller's staged
+                     * view. Without it `/sources/~` replays every pending patch on the
+                     * branch, so a server-rendered preview shows other people's
+                     * unpublished work — the one thing independent publish is for.
+                     *
+                     * Omitted means everything pending, which is the behaviour every
+                     * existing caller has and must keep. An EMPTY array is a different
+                     * answer and is honoured as one: a group holding nothing renders
+                     * base.
+                     */
+                    patch_id: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    /**
+                     * Apply only the patches in the CALLER'S OWN patch groups.
+                     *
+                     * The server resolves them from the session, so a draft render does
+                     * not have to know its own group ids — which it cannot, since it has
+                     * no client state. This is what makes `fetchVal` in draft mode show
+                     * the person their own staged work rather than everybody's.
+                     *
+                     * Ignored when `patch_id` is given: an explicit list is a caller that
+                     * already knows what it wants, and silently intersecting the two
+                     * would make the narrower one invisible.
+                     */
+                    own_patch_groups_only: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
                 };
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -876,6 +1025,8 @@ export declare const Api: {
                 body: z.ZodObject<{
                     message: z.ZodOptional<z.ZodString>;
                     patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    patchGroupId: z.ZodOptional<z.ZodString>;
+                    expectedHeadCommitSha: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -889,6 +1040,7 @@ export declare const Api: {
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
                 json: z.ZodObject<{
+                    commitSha: z.ZodOptional<z.ZodString>;
                     removed: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
                         moduleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
@@ -896,11 +1048,29 @@ export declare const Api: {
                     }, z.core.$strip>>>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
-                status: z.ZodLiteral<409>;
+                status: z.ZodLiteral<403>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
                 json: z.ZodObject<{
                     message: z.ZodString;
-                    isNotFastForward: z.ZodLiteral<true>;
                 }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<409>;
+                json: z.ZodUnion<readonly [z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    message: z.ZodString;
+                    isNotFastForward: z.ZodLiteral<true>;
+                }, z.core.$strip>, z.ZodObject<{
+                    message: z.ZodString;
+                    headMoved: z.ZodLiteral<true>;
+                }, z.core.$strip>, z.ZodObject<{
+                    message: z.ZodString;
+                    patchGroupPublished: z.ZodLiteral<true>;
+                }, z.core.$strip>]>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<400>;
                 json: z.ZodUnion<readonly [z.ZodObject<{
@@ -965,6 +1135,15 @@ export declare const Api: {
                     offset: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>, z.ZodTransform<number, string>>>;
                     limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>, z.ZodTransform<number, string>>>;
                     apply_patches: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
+                    /**
+                     * The caller's own staged work, and nobody else's.
+                     *
+                     * The same flag `/sources/~` takes, and for the same reason — a draft
+                     * page renders both, so a scoped module beside an unscoped
+                     * `jsonValues` entry showed one person's view and everybody's pending
+                     * work on the same screen.
+                     */
+                    own_patch_groups_only: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>> & z.ZodType<"true" | "false", string[], z.core.$ZodTypeInternals<"true" | "false", string[]>>, z.ZodTransform<boolean, "true" | "false">>>;
                 };
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;

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

@@ -3,6 +3,7 @@ export * from "./server/types.js";
 export * from "./ValClient.js";
 export * from "./ValUrls.js";
 export * from "./ApiRoutes.js";
+export * from "./newestCommitSha.js";
 export * from "./zod/Patch.js";
 export * from "./sessionStorage.js";
 export * from "./SharedValConfig.js";

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

@@ -0,0 +1,20 @@
+import type { ValCommit } from "./zod/ValCommit.js";
+/**
+ * The newest commit the client has been told about, or `null` if none.
+ *
+ * This is the **publish head**: unlike `baseSha`, which only moves once a
+ * deployment lands, it moves the instant somebody publishes. That makes it the
+ * one thing a client can carry to `/save` to say "this is the world I decided
+ * against" — and the only way the server can tell that somebody else has
+ * published since the review screen was read.
+ *
+ * In `shared` because both sides need the SAME answer: the client names a head
+ * and the server compares against one, so two implementations of "newest" is two
+ * ways to disagree about whether a publish is stale.
+ *
+ * By `createdAt` rather than by position, because the list's order is the
+ * content API's business and nothing here should depend on it. Ties keep the
+ * first seen, which is arbitrary and does not matter: two commits sharing a
+ * timestamp are equally "since", and either answer refuses the same publishes.
+ */
+export declare function newestCommitSha(commits: readonly ValCommit[] | undefined): string | null;