@valbuild/shared 0.150.20 → 0.151.0

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # @valbuild/shared
 
+## 0.151.0
+
+### Patch Changes
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`59faf33`](https://github.com/valbuild/val/commit/59faf332418af836617e09150fb89007e468394e) Thanks [@freekh](https://github.com/freekh)! - Code mode now works in a hosted Studio. In a proposal, the `</>` beside the
+  proposal's name turns code mode on for everyone in it, and the assistant can
+  then change the proposal's code. On the site, the `</>` lists the open
+  proposals and opens the one you choose with code mode on.
+
+  - **Nothing you typed is lost when code changes.** Turning code mode on saves
+    every pending change first, and so does each of the assistant's code
+    changes, so a field the assistant adds can be filled in and stays filled
+    in. Turning code mode off discards nothing.
+  - **Each person chooses what they see.** While code mode is on you can stay
+    in the content editor, or see the proposal's preview and its code changes.
+    The proposal's menu says who turned code mode on, and when.
+  - **The assistant asks.** With code mode off, its code tools refuse and say
+    who turned it off; it asks for code mode with a button in the chat instead.
+  - **Save is the one main button** in a proposal, and also updates the
+    preview when the code changed. Its menu holds **Commit**, in a project
+    connected to git, which puts the proposal on its git branch as one commit,
+    and **Publish**, which commits and then merges into the site. Both use the
+    project's commit message setting. In code mode, Save saves even when
+    content has validation errors; Publish is still refused until they are
+    fixed. If someone else pushed to the proposal's branch, Commit says who and
+    when, and links to their commit, instead of committing over it.
+  - The "schema changed, reload" dialog is not shown in code mode, where the
+    schema changes with every build.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`abf6148`](https://github.com/valbuild/val/commit/abf6148a255abe795620fede66006462bccb8322) Thanks [@freekh](https://github.com/freekh)! - The assistant's code tools now see a publish of the site made while the Studio
+  is open. They read the site's code once and kept that copy for as long as the
+  page was open, so a file published in the meantime was shown as it was before.
+  They now ask on every call, and the content service answers "unchanged" without
+  sending the code again unless it did change.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`1f08b65`](https://github.com/valbuild/val/commit/1f08b6517adeac27fd9e43c7bf726976daefee3b) Thanks [@freekh](https://github.com/freekh)! - Search and a library entry's "used by" no longer freeze the Studio on a large `.jsonValues()` record.
+
+  Both have to see every entry of the records they look in. The Studio used to ask for those entries one request at a time and rebuild the record after each one, which grew with the square of the record's size: about a second for 1,000 entries, and most of a minute for 10,000. Now:
+
+  - entries are requested many to a request (`GET /json` with a list of keys), with at most three such requests at a time, so what you open meanwhile is not queued behind them;
+  - what arrives is applied a batch at a time, with the browser free to handle clicks and typing between batches;
+  - search and "used by" show a progress bar with how many entries are loaded, show what they have found so far, and offer **Try again** if some entries could not be loaded;
+  - closing search or leaving the entry stops the requests that have not been sent;
+  - the search index adds only the entries that arrived, rather than re-reading the whole record each time.
+
+  A record's rows on screen are now also fetched in one request rather than one per row.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`04bae7e`](https://github.com/valbuild/val/commit/04bae7e54e6b191fc70f45e6f10bbce820b6069c) Thanks [@freekh](https://github.com/freekh)! - **No more "A new version has been deployed" dialog.** A Studio that is open
+  while the site is deployed no longer stops you with a dialog you can only
+  answer by reloading. Instead:
+
+  - **On Val's hosting**, the Studio takes the new build's fields in where you
+    are, without reloading: a field the deploy added can be filled in at once,
+    and the assistant's chat, the page you were on and your unsaved edits stay
+    as they were. Each build now carries its content schemas as a small file of
+    its own beside its scripts, which the Studio loads.
+  - **Anywhere else** (a Next.js site, or a TanStack Start site hosted
+    somewhere else), the Studio reloads itself a few seconds after the deploy,
+    once everything you typed has been saved. Nothing is lost: where you were is
+    in the address, and every edit is on the server.
+  - **In local development** nothing changes: your dev server's hot reload
+    brings the new fields, as before.
+
+  When a deploy upgrades Val itself, the Studio reloads itself the same way,
+  since its own code changed too.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`4fd35f3`](https://github.com/valbuild/val/commit/4fd35f321fe510cfb5b9b679ca14ce2b9e852d40) Thanks [@freekh](https://github.com/freekh)! - Unpublished edits are now applied the same way everywhere the server reads
+  them, and a few cases that showed something different from what Publish would
+  save are fixed:
+
+  - A field you emptied to `null`, `""`, `0` or `false` no longer jumps back to
+    its published value at your next edit.
+  - When an edit cannot be applied, later edits to `.jsonValues()` entries stop
+    there too, instead of showing an entry the page will never get.
+  - An image or file added to a `.jsonValues()` entry no longer fails the whole
+    entry when the upload comes before the field in the edit.
+  - Clearing a nullable `.jsonValues()` record removes its entries from drafts
+    as well.
+
+  Long chains of unpublished edits are also much faster to read: a draft with
+  650 edits went from about 580 ms to about 110 ms.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`346e6fd`](https://github.com/valbuild/val/commit/346e6fdc8e242bf826ab66a729eacd9f8d4be1a6) Thanks [@freekh](https://github.com/freekh)! - **Draft pages read what was edited, not the whole site.** A page in draft
+  mode used to make Val's server read every module, apply every pending
+  change, and preview and validate the whole project on every request -- and
+  then ask again for each `.jsonValues()` entry it showed. Now there is one
+  copy of the draft per process, made once per change and shared by every
+  editor and every request:
+
+  - A module nobody edited costs nothing: the page reads its own build, as a
+    visitor's does.
+  - A request asks one cheap question -- has anything changed? -- once, and
+    the draft is only re-read when it has. An edit is applied once, to the
+    version before it, however many pages read it afterwards.
+  - `fetchVal`, `fetchValKey`, `fetchValRoute`, `fetchValRouteUrl` and
+    `fetchValDraft` (Next.js and TanStack Start alike) and Val's API routes
+    read that one copy, so a save through the API is seen by every reader at
+    once. Before, each kept its own, and a publish moved only the copy of the
+    server that handled it: in a host that keeps its content in memory, a
+    draft page read through `fetchValKey` or `fetchValRoute` went on showing
+    the content from before the publish.
+  - The MCP tools (`initValMcp`) read the same copy in local development and
+    on Val's hosting, where Val's options come from your config and the
+    environment. `initValMcp` takes no patch store or source files of its
+    own, so in a host that keeps its content in memory it keeps a copy of its
+    own, as before.
+  - If `initValServer` and `initValContent` (or `initValRsc`) are given
+    different options for the same `val.modules` (a different patch store,
+    say), they keep separate copies, and Val logs a warning saying which
+    options differ.
+
+  On a site of 20 MB of content a draft read went from about half a second per
+  request to well under a millisecond once the draft is in memory, and the
+  memory it holds grows with what was edited rather than with the size of the
+  site. Hosted sites in proxy mode ask the content service one small question
+  per request instead of reading every pending change; with a content service
+  that predates it, Val reads the pending changes as before.
+
+  `ValDraft` (what `fetchValDraft` returns and `<ValProvider draft>` takes)
+  has a new optional `versions` field, filled in by the server: the page uses
+  it to tell that what the Studio sends is what it already shows, without
+  comparing the content. Nothing to change in your app.
+
+  **Changed:** `PUT /api/val/sources/~` no longer computes previews or
+  validates the content (the Studio does both itself, and `/api/val/validate`
+  checks a module on request); its `validate_sources` and
+  `validate_binary_files` flags are accepted and ignored.
+
+  **Deprecated, and removed in the next release.** These stay for one release
+  only so that a Studio, a page or a server of the previous release keeps
+  working while a deploy rolls out. Nothing in this release uses them; if
+  your own code calls any of them, move off it now:
+
+  - `PUT /api/val/sources/~`, the whole route. This release's Studio reads
+    `GET /api/val/manifest` and `GET /api/val/modules/~<path>`, and the draft
+    readers and MCP read in-process.
+  - The `source` field of the overlay's `source-update` event and the canvas's
+    `sourceUpdate` message, and a page's support for an event that carries
+    only `source` (this release sends `read` beside it).
+  - `ValDraft.base`: not sent and not read; the type stays one release so
+    code written against the previous one still compiles.
+  - `/api/val/stat`'s `sourcesSha` and `schemaSha`: the next release's Studio
+    stops depending on them, and the release after it stops sending them.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`b0ad7f4`](https://github.com/valbuild/val/commit/b0ad7f496f2dc0384b8df847b1d77becf617b7bf) Thanks [@freekh](https://github.com/freekh)! - A draft page now catches up with an edit as soon as the server has it, instead
+  of on a timer.
+
+  - **The page settles faster, and without the 10 second fallback.** Content your
+    page reads on the server (a TanStack Start loader, a Next.js server component)
+    is refreshed when the editor's change has been saved, once per saved change.
+    It used to be refreshed the moment you typed — before the change was saved,
+    so the refresh often came back without it — and then again every 10 seconds
+    for half a minute in case it had. That safety refresh is gone, and so are the
+    extra requests it made while you edited. Another editor's change refreshes
+    the page too, once the server has it. While a deploy rolls out, a Studio of
+    the previous release (which never says it has saved) still refreshes the
+    page as each change arrives, as before.
+  - **Next.js: `ValProvider` takes an optional `draft` prop**, as
+    `@valbuild/tanstack`'s does: the editor's draft, read on the server for the
+    request. With it, the server renders the draft and the browser hydrates the
+    same thing, so a draft page no longer shows the published text first, and a
+    page that exists only as an unpublished change is found on the first render
+    instead of answering 404. Without it, nothing changes. See "The `draft` prop"
+    in the `@valbuild/next` README.
+  - **Next.js: `initValRsc` returns `fetchValDraft`**, which reads that draft:
+    pass `draft={await fetchValDraft()}` to `ValProvider` in your root layout. It
+    returns `null` unless the request is in draft mode, after one `draftMode()`
+    lookup and no other work, so visitors pay nothing and a static page stays
+    static. It reads the draft the way `@valbuild/tanstack/server`'s
+    `fetchValDraft` does and returns the same type, `ValDraft | null`, which
+    is now exported from `@valbuild/next` and `@valbuild/next/rsc` too.
+  - **`suspend` waits for the editor's changes properly.** With `suspend` on
+    `ValProvider`, a page could be told it had everything before the editor had
+    sent the pending change it needed, and render the published content first —
+    for a page that exists only as an unpublished change, a 404. It now waits
+    until the change is there.
+  - A draft page whose draft was discarded or published before the editor's
+    overlay or canvas connected now shows what the editor has, instead of keeping
+    the draft it was rendered with -- an edit inside a `.jsonValues()` entry
+    included.
+  - Turning draft mode on or off refreshes the page once. In development (React's
+    `StrictMode`) it could refresh twice, and Next.js could log "Cannot call
+    startTransition while rendering" while the page refreshed.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`3aff85e`](https://github.com/valbuild/val/commit/3aff85e9a40cb0879285b86fd41fa8167db1bb5e) Thanks [@freekh](https://github.com/freekh)! - **A JSON Patch `test` op now fails when it does not hold.** A `test` op is a
+  precondition: "only apply this patch if the value at this path is still
+  this". Val used to accept every `test` op without checking it, so a patch
+  that should have been refused was applied anyway.
+
+  Now a `test` op fails its patch when the path does not exist, or when the
+  value there is not deeply equal to the one given (objects and arrays are
+  compared all the way down, and `0`, `""`, `false` and `null` are all
+  different from each other). The ops after it are not applied. This holds in
+  every place Val applies a patch -- the Studio's drafts, a draft page, the
+  content tools for MCP, and Publish -- so a patch a draft shows is a patch
+  Publish accepts.
+
+  Nothing in the Studio, the CLI or the content tools writes `test` ops of
+  its own, so this only changes anything for a patch you, or an agent through
+  the MCP `create_patch` tool, wrote with a `test` op in it: one whose test
+  does not hold is now refused with `Test failed` (or, for a path that does
+  not exist, `Path refers to non-existing object/array`) instead of applied.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`809873c`](https://github.com/valbuild/val/commit/809873cd7dd2c17e261b7e92716397a6bb4d6e56) Thanks [@freekh](https://github.com/freekh)! - Every content reader in `@valbuild/next` and `@valbuild/tanstack` — `fetchVal`,
+  `useVal`, the key and route readers, on the server and in the browser — now
+  loads content the same way, so they can no longer disagree about which content
+  wins. Nothing you call changes. What you may notice:
+
+  - `useValRoute` on a `.jsonValues()` router loads only the entry for the
+    current route. It used to load every entry of the record first.
+    `useValRouteUrl` and `fetchValRouteUrl` load none at all: a URL does not need
+    them.
+  - In development, an edited `*.val.json` entry shows its new content after a
+    hot reload. The hooks kept the entry they had loaded before it.
+  - Next.js: `useValKey` no longer shows the published entry of a nullable
+    `.jsonValues()` record that a draft has set to `null`, nor anything for an
+    entry named like a built-in object property (such as `toString`) that the
+    draft does not have.
+  - With `suspend` on `ValProvider`, `useValKey` now waits for draft mode and the
+    editor's changes too, as `useVal` and `useValRoute` already did.
+  - When one entry of a `.jsonValues()` record cannot be loaded, `useVal` logs
+    the error and renders the others, as `fetchVal` already did, instead of
+    failing the whole component.
+
+- [#1006](https://github.com/valbuild/val/pull/1006) [`4dc1481`](https://github.com/valbuild/val/commit/4dc1481cfb7cad4072bdbeaeb51b2b2ad43a9f5d) Thanks [@freekh](https://github.com/freekh)! - The Studio now shows each module as your server has it, by version, with only your own unsaved edits on top.
+
+  - **Publishing is faster.** After a publish, or when your site serves content published without a build, the Studio used to download every module's content before it showed anything new. It now reads only the modules that changed, one at a time: in our measurements with a 1,000-entry `.jsonValues()` record, the Studio was ready again after a publish in about 35 ms instead of 300–800 ms.
+  - **No flicker of old content on a draft page.** For up to a minute after a deploy, a request can still reach the build before it; that build now says it has been replaced (when Val's content service can tell it), and the Studio asks again rather than taking its content for the current one. In local development the same holds after you change a `.val.ts`: an answer from the code before the change is no longer taken for the new code's, so a page in draft mode no longer shows the new text, then the old, then the new again.
+  - **Another editor's change appears as your server has it.** The Studio no longer replays other people's changes on top of the content it loaded with, so a change made against a newer deployment can no longer show up twice or out of order.
+  - **Less sent with every draft page.** A page in draft mode no longer embeds the whole published content of a site served without a rebuild for the Studio to start from; `ValDraft.base` is deprecated and no longer filled in.
+  - **When the editor opens on a page that already shows your changes,** the Studio no longer sends them to the page again.
+
+- [#1011](https://github.com/valbuild/val/pull/1011) [`4edd384`](https://github.com/valbuild/val/commit/4edd384cf04a25836df77aae6d88378f8750a761) Thanks [@freekh](https://github.com/freekh)! - Requests that `@valbuild/server` and the `val` CLI send to Val Build now carry an `x-val-client` header naming the package and its version, for example `x-val-client: @valbuild/server@0.150.24`. It lets Val Build see which versions are still in use, and which old endpoints they still call, before anything is retired. The header holds no credential and nothing about your site's visitors, and nothing changes in how your app behaves.
+- Updated dependencies [[`a325152`](https://github.com/valbuild/val/commit/a325152856a881faec84c112fcf226828739f563), [`f5110c9`](https://github.com/valbuild/val/commit/f5110c9aa2a0a6ff0586e9f0f2a29eb1baef557d), [`3aff85e`](https://github.com/valbuild/val/commit/3aff85e9a40cb0879285b86fd41fa8167db1bb5e)]:
+  - @valbuild/core@0.151.0
+
 ## 0.150.20
 
 ### Patch Changes

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

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var getSitemapTree = require('../../dist/getSitemapTree-6dfa2f4e.cjs.dev.js');
+var getSitemapTree = require('../../dist/getSitemapTree-59c5ed5d.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-f2d7ac6d.cjs.dev.js');
 require('@valbuild/core');
 

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

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var getSitemapTree = require('../../dist/getSitemapTree-8a04f3cf.cjs.prod.js');
+var getSitemapTree = require('../../dist/getSitemapTree-6b9024d1.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-9ca2078d.cjs.prod.js');
 require('@valbuild/core');
 

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

@@ -1,3 +1,3 @@
-export { D as DEFAULT_CANVAS_SELECTION, e as DEFAULT_CANVAS_SELECTION_SOFT, Q as QUICK_PREVIEW_PARAM, v as QUICK_PREVIEW_RENDER_SCRIPT, u as QUICK_PREVIEW_SERVICE_WORKER_PATH, z as QUICK_PREVIEW_SERVICE_WORKER_SOURCE, x as QUICK_PREVIEW_STORE_MESSAGE, b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, j as attachElementPicker, k as createPickerOverlay, h as describeElement, l as elementLabel, q as findBySelector, G as formatRoutePattern, H as getNextAppRouterSourceFolder, L as getPageRouterSitemapTree, J as getPageRouterSourceFolder, M as getPatternFromModuleFilePath, I as getTanStackRouterSourceFolder, E as isDesignTabOrigin, y as isQuickPreviewFiles, K as isTanStackRoutesFolder, g as isValCanvasFrame, i as isValCanvasPageMessage, f as isValCanvasStudioMessage, m as modifierLabel, p as pageLocationOf, F as parseRoutePattern, C as quickPreviewSiteOrigin, o as readPageSnapshot, r as restoreScroll, t as screenshotPage, s as startElementPicking, A as storeQuickPreview, n as watchPageLocation, B as withQuickPreviewParam, w as withValCanvasParam } from '../../dist/getSitemapTree-fef55872.esm.js';
+export { D as DEFAULT_CANVAS_SELECTION, e as DEFAULT_CANVAS_SELECTION_SOFT, Q as QUICK_PREVIEW_PARAM, v as QUICK_PREVIEW_RENDER_SCRIPT, u as QUICK_PREVIEW_SERVICE_WORKER_PATH, z as QUICK_PREVIEW_SERVICE_WORKER_SOURCE, x as QUICK_PREVIEW_STORE_MESSAGE, b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, j as attachElementPicker, k as createPickerOverlay, h as describeElement, l as elementLabel, q as findBySelector, G as formatRoutePattern, H as getNextAppRouterSourceFolder, L as getPageRouterSitemapTree, J as getPageRouterSourceFolder, M as getPatternFromModuleFilePath, I as getTanStackRouterSourceFolder, E as isDesignTabOrigin, y as isQuickPreviewFiles, K as isTanStackRoutesFolder, g as isValCanvasFrame, i as isValCanvasPageMessage, f as isValCanvasStudioMessage, m as modifierLabel, p as pageLocationOf, F as parseRoutePattern, C as quickPreviewSiteOrigin, o as readPageSnapshot, r as restoreScroll, t as screenshotPage, s as startElementPicking, A as storeQuickPreview, n as watchPageLocation, B as withQuickPreviewParam, w as withValCanvasParam } from '../../dist/getSitemapTree-3c1b9e57.esm.js';
 import '../../dist/createForOfIteratorHelper-9b80f1a2.esm.js';
 import '@valbuild/core';

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

@@ -512,6 +512,75 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    /**
+     * What each module IS, right now: its version (`schema`, `base`, `chain`),
+     * and the project version that is relative to. What `/stat` answers, per
+     * module; see `docs/plans/one-content-model.md`, "The Studio loads
+     * everything from one place".
+     *
+     * It has its own ETag, so a client that sends it back (`If-None-Match`)
+     * gets a 304 and no body while nothing has moved. Computed from versions
+     * kept as content changes: answering it hashes nothing.
+     *
+     * "Since `seq` N" (`?since=N`, with the ETag of the manifest the client
+     * holds, which was answered at `seq` N, as `If-None-Match`): the modules
+     * whose version moved since that manifest, and no others, with `since: N`
+     * on the answer to say it is a delta. The ETag is in the body too (`tag`),
+     * for a client that reads answers through `ValClient`, which hands over
+     * the body and not the headers. Answered whole -- no `since` -- when the server no
+     * longer holds the manifest that ETag names (another process, another
+     * build, too long ago), and by a server of the release before, which
+     * ignores the parameter. Optional both ways.
+     */
+    "/manifest": {
+        GET: {
+            req: {
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                headers: {
+                    "if-none-match": z.ZodOptional<z.ZodString>;
+                };
+                query: {
+                    since: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                };
+            };
+            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<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    project: z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>;
+                    modules: z.ZodRecord<z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>, z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
+                    tag: z.ZodOptional<z.ZodString>;
+                    since: z.ZodOptional<z.ZodNumber>;
+                    superseded: z.ZodOptional<z.ZodBoolean>;
+                    registry: z.ZodOptional<z.ZodObject<{
+                        entry: z.ZodString;
+                        core: z.ZodString;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<304>;
+                json: z.ZodOptional<z.ZodNull>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/stat": {
         POST: {
             req: {
@@ -580,6 +649,10 @@ export declare const Api: {
                         branch: z.ZodString;
                     }, z.core.$strip>>;
                     historyBranch: z.ZodOptional<z.ZodString>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"use-websocket">;
                     url: z.ZodString;
@@ -634,6 +707,10 @@ export declare const Api: {
                         branch: z.ZodString;
                     }, z.core.$strip>>;
                     historyBranch: z.ZodOptional<z.ZodString>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
@@ -675,11 +752,17 @@ export declare const Api: {
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
                 };
+                headers: {
+                    "if-none-match": z.ZodOptional<z.ZodString>;
+                };
             };
-            res: z.ZodObject<{
+            res: z.ZodUnion<readonly [z.ZodObject<{
                 status: z.ZodNumber;
                 json: z.ZodUnknown;
-            }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<304>;
+                json: z.ZodOptional<z.ZodNull>;
+            }, z.core.$strip>]>;
         };
         POST: {
             req: {
@@ -1284,6 +1367,10 @@ export declare const Api: {
                     errors: z.ZodOptional<z.ZodRecord<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>, z.ZodObject<{
                         message: z.ZodString;
                     }, z.core.$strip>>>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
@@ -1326,6 +1413,15 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    /**
+     * @deprecated The whole tree. Nothing of this release asks it: the Studio
+     * reads modules by version (`GET /manifest`, `GET /modules/~`), the draft
+     * readers and MCP read the head in-process. Kept, with `exclude_patches`
+     * (`BaseAlignment`'s fetch) and the ignored `validate_sources` and
+     * `validate_binary_files`, for a Studio of the release before; goes in the
+     * release after the one that ships this (see "Release-delayed deletions"
+     * in `docs/plans/one-content-model.md`).
+     */
     "/sources/~": {
         PUT: {
             req: {
@@ -1397,8 +1493,153 @@ export declare const Api: {
                             fatal: z.ZodOptional<z.ZodBoolean>;
                             fixes: z.ZodOptional<z.ZodArray<z.ZodType<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "video:add-metadata" | "video:upload-remote" | "video:download-remote" | "videos:add-metadata" | "videos:check-remote" | "videos:upload-remote" | "keyof:check-keys" | "image:check-gallery" | "file:check-gallery" | "video:check-gallery" | "router:check-route" | "locale:check-locale" | "router:check-locale-param" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "videos:check-unique-folder" | "videos:check-all-files" | "jsonValues:extract-entry" | "record:fill-keys" | "external:upload" | "view:check-module" | "remote:rewrite-host", unknown, z.core.$ZodTypeInternals<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "video:add-metadata" | "video:upload-remote" | "video:download-remote" | "videos:add-metadata" | "videos:check-remote" | "videos:upload-remote" | "keyof:check-keys" | "image:check-gallery" | "file:check-gallery" | "video:check-gallery" | "router:check-route" | "locale:check-locale" | "router:check-locale-param" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "videos:check-unique-folder" | "videos:check-all-files" | "jsonValues:extract-entry" | "record:fill-keys" | "external:upload" | "view:check-module" | "remote:rewrite-host", unknown>>>>;
                         }, z.core.$strip>>>>;
+                        version: z.ZodOptional<z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                        }, z.core.$strip>>;
+                    }, z.core.$strip>>;
+                    project: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * One module by version: phase 6 of `docs/plans/one-content-model.md`
+     * ("The Studio loads everything from one place"). `GET /modules/~<path>`,
+     * with `v` the version wanted as its `moduleKey` (the newest when absent;
+     * a base is a version with the empty chain) and `have` the version the
+     * caller holds: when the caller's chain is a start of the answer's under
+     * the same schema and base, the answer is the patches from it (`delta`),
+     * otherwise the whole module. An answer for an asked `v` is immutable.
+     */
+    "/modules/~": {
+        GET: {
+            req: {
+                path: z.ZodString;
+                query: {
+                    v: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                    have: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                };
+                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<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                    current: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
                     }, z.core.$strip>>;
                 }, 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>;
+                headers: z.ZodOptional<z.ZodObject<{
+                    "Cache-Control": z.ZodString;
+                }, z.core.$strip>>;
+                json: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"module">;
+                    version: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    source: z.ZodAny;
+                    entries: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        content: z.ZodAny;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        deleted: z.ZodLiteral<true>;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        error: z.ZodString;
+                        patchId: z.ZodOptional<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>]>>;
+                    patches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    failed: z.ZodOptional<z.ZodObject<{
+                        patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
+                        message: z.ZodString;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"delta">;
+                    from: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    patches: z.ZodArray<z.ZodObject<{
+                        patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
+                        patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                            op: z.ZodLiteral<"add">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"remove">;
+                            path: z.ZodTuple<[z.ZodString], z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"replace">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"move">;
+                            from: z.ZodTuple<[z.ZodString], z.ZodString>;
+                            path: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"copy">;
+                            from: z.ZodArray<z.ZodString>;
+                            path: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"test">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"file">;
+                            path: z.ZodArray<z.ZodString>;
+                            filePath: z.ZodString;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                            remote: z.ZodBoolean;
+                            nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+                        }, z.core.$strict>], "op">>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
     };
@@ -2259,6 +2500,11 @@ export declare const Api: {
                     path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
                     key: z.ZodString;
                     content: z.ZodAny;
+                    version: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
@@ -2276,6 +2522,11 @@ export declare const Api: {
                     offset: z.ZodOptional<z.ZodNumber>;
                     limit: z.ZodOptional<z.ZodNumber>;
                     total: z.ZodOptional<z.ZodNumber>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<400>;