@valbuild/server 0.144.1 → 0.144.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @valbuild/server
 
+## 0.144.3
+
+### Patch Changes
+
+- Updated dependencies [[`99fcac5`](https://github.com/valbuild/val/commit/99fcac527f2d5ba37c4b132ef08189b955d69e51), [`0e09e9c`](https://github.com/valbuild/val/commit/0e09e9cdac4918bdfa1c01a92a8968a516f8c0c6)]:
+  - @valbuild/ui@0.144.3
+
+## 0.144.2
+
+### Patch Changes
+
+- [#832](https://github.com/valbuild/val/pull/832) [`ab0ea20`](https://github.com/valbuild/val/commit/ab0ea2046e3872c4955f34b363881f76d48d1b1e) Thanks [@freekh](https://github.com/freekh)! - A site served by Val's platform can now be given its content separately from its build. When the platform hands a TanStack app a content version (`VAL_CONTENT`) that differs from what the build bundles, Val renders that content, in the Studio and in draft mode too. It reads it the way it already reads a proposal's saved content.
+
+  Nothing changes for an app that is not given one, and nothing hands one over yet. This is the reading side of publishing content without rebuilding the site.
+
+  A version too large for one environment variable can name others under `refs` (`"env://VAL_CONTENT_1"`), each holding one module's Source or one file's text. Only `refs` is resolved, never a string inside your content, and only variables named `VAL_CONTENT_<n>` are read.
+
+  At a proposal's address, a proposal's saved content is shown over the content version the site serves, so modules the proposal did not change show what the site shows rather than what the build bundles.
+
+  When Val's platform puts a publish live without building the site, because it changed only content, the Studio shows it being checked and going live instead of "Building".
+
+- Updated dependencies [[`ab0ea20`](https://github.com/valbuild/val/commit/ab0ea2046e3872c4955f34b363881f76d48d1b1e), [`44a5636`](https://github.com/valbuild/val/commit/44a5636955e005a40f2e6c8544e5cf4378fd0fdf)]:
+  - @valbuild/shared@0.144.2
+  - @valbuild/ui@0.144.2
+
 ## 0.144.1
 
 ### Patch Changes

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

@@ -51,6 +51,14 @@ export type ValOpsOptions = {
      * the next save's prepare -- starts from it, and the SHAs describe it.
      */
     snapshotSources?: Sources;
+    /**
+     * Source the SITE serves over what the modules evaluate to, beneath
+     * {@link snapshotSources}: a content version (`ValContentVersion` in
+     * `./proposal`), the content published since the build. Applied the same
+     * way, and what a proposal's saves are compared against
+     * ({@link ValOps.siteSourcesUnderSnapshot}) -- the site, not the bundle.
+     */
+    siteSnapshotSources?: Sources;
     /**
      * The `.jsonValues()` entries the same snapshot saved, by module and key:
      * their content is in their own files, not in {@link snapshotSources}, which
@@ -97,6 +105,13 @@ export declare abstract class ValOps {
      * {@link siteSourcesUnderSnapshot}, and only where there is a snapshot.
      */
     private siteSourcesBeforeSnapshot;
+    /**
+     * The same modules as the bundle evaluated them, imports and all: where a
+     * `.jsonValues()` entry the snapshot did not save is read from. Not
+     * {@link siteSourcesBeforeSnapshot}, whose markers may have come as JSON
+     * from a content version, with no import behind them.
+     */
+    private bundleSourcesBeforeSnapshot;
     /**
      * What a save has told us each `.jsonValues()` entry now holds.
      *

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

@@ -1,4 +1,4 @@
-import { type ValProposal } from "./proposal.js";
+import { type ValContentVersion, type ValProposal } from "./proposal.js";
 import { type PatchId, type ModuleFilePath, ValModules } from "@valbuild/core";
 import type { Patch as PatchT, ParentRef as ParentRefT } from "@valbuild/core/patch";
 import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha, type PublishRefusal } from "./ValOps.js";
@@ -81,6 +81,8 @@ export declare class ValOpsHttp extends ValOps {
     private readonly publishBuild;
     /** See `proposal` on {@link ValApiOptions}; `null` on the site. */
     private readonly proposal;
+    /** See `contentVersion` on {@link ValApiOptions}; `null` at a proposal's address. */
+    private readonly contentVersion;
     /** Did the host hand over the running build's source? See `projectSource`. */
     embedsSource(): boolean;
     /**
@@ -153,6 +155,8 @@ export declare class ValOpsHttp extends ValOps {
         publishBuild?: string;
         /** See `proposal` on {@link ValApiOptions}. */
         proposal?: ValProposal;
+        /** See `contentVersion` on {@link ValApiOptions}. */
+        contentVersion?: ValContentVersion;
     });
     /**
      * A deployment that cannot mirror a project which expects to be mirrored.

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

@@ -8,7 +8,7 @@ type Versions = {
     };
 };
 import type { ValPatchStore } from "./ValOpsMemory.js";
-import type { ValProposal } from "./proposal.js";
+import type { ValContentVersion, ValProposal } from "./proposal.js";
 import type { CommitContext, CommitResult } from "./ValServer.js";
 export type ValApiOptions = ValServerOverrides & ValConfig & Versions;
 type ValServerOverrides = Partial<{
@@ -163,6 +163,14 @@ type ValServerOverrides = Partial<{
      * and the snapshot that replaces the bundle's Source for what it saved.
      */
     proposal?: ValProposal;
+    /**
+     * The content version the site serves, when a platform says it differs from
+     * the one this build bundles (`VAL_CONTENT`; read it with `contentFromEnv`).
+     * See {@link ValContentVersion}: its Source replaces the bundle's for what
+     * it holds, and its publish is this server's position. Ignored at a
+     * proposal's address.
+     */
+    contentVersion?: ValContentVersion;
     /**
      * The base url of Val.
      *

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

@@ -1,4 +1,4 @@
-import type { ValProposal } from "./proposal.js";
+import type { ValContentVersion, ValProposal } from "./proposal.js";
 import { ValModules, PatchId, ModuleFilePath, ValConfig } from "@valbuild/core";
 import { Api, ServerOf, type PatchGroupT } from "@valbuild/shared/internal";
 import { z } from "zod";
@@ -148,6 +148,8 @@ export type ValServerConfig = ValServerOptions & ({
     publishBuild?: string;
     /** See `proposal` on {@link ValApiOptions}. */
     proposal?: ValProposal;
+    /** See `contentVersion` on {@link ValApiOptions}. */
+    contentVersion?: ValContentVersion;
     config: ValConfig;
 }
 /**

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

@@ -2,8 +2,8 @@ export { createService, Service } from "./Service.js";
 export { defineExternal, ok, err, isExternalResult, EXTERNAL_RESULT, } from "./externalRecords.js";
 export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder, ExternalCtx, ExternalDefinition, ExternalFile, ExternalIssue, ExternalKeyPage, ExternalRecords, ExternalResult, ExternalSearchHit, ExternalSearchPage, ExternalSort, ItemOfModule, ReadonlyRecordHasNoWrites, Returns, } from "./externalRecords.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
-export { proposalFromEnv, proposalSnapshot, proposalSnapshotForReaders, } from "./proposal.js";
-export type { ValProposal } from "./proposal.js";
+export { contentFromEnv, proposalFromEnv, layeredSnapshot, proposalSnapshot, proposalSnapshotForReaders, } from "./proposal.js";
+export type { ValContentVersion, ValProposal } from "./proposal.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
 export { resolveRemoteFileAuth } from "./valServerConfig.js";
 export { APP_MODE_REQUIRES_REMOTE_FILES } from "./valServerConfig.js";

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

@@ -65,6 +65,59 @@ export declare function proposalFromEnv(env: {
     VAL_BRANCH?: string | undefined;
     VAL_OVERLAY?: string | undefined;
 }): ValProposal | undefined;
+/**
+ * A content version: the site's content, served by a build that bundles an
+ * older one. valbuild/home `docs/hosted-publishing.md`, step 2.
+ *
+ * The platform hands over only what differs from the bundle -- the modules
+ * whose Source changed and the Val files whose text did -- the way it hands a
+ * proposal's address its saved content, and it is read the same way: the
+ * snapshot source provider, over the bundle. What differs is the position: a
+ * version names the publish that made it (`job`, or its `commit`), and that is
+ * where this server says it sits, never at the build it runs in.
+ */
+export type ValContentVersion = {
+    /** The version's id: the hash of its manifest, as the platform stores it. */
+    id: string;
+    /** The publish job that made it, when a job did. */
+    job: string | null;
+    /** Its place in the chain: the commit that publish minted. */
+    commit: string | null;
+    /** Source, by module file path, for the modules that differ from the bundle. */
+    modules: Record<string, unknown>;
+    /** Val file text, by path, for the files that differ from the bundle. */
+    files: Record<string, string>;
+};
+/**
+ * The content version a platform hands over in its runtime env
+ * (`VAL_CONTENT`), or `undefined` when it hands over none.
+ *
+ * Throws on one it cannot read rather than serving the bundle as though it
+ * were the version: the site would show content older than what was
+ * published, and nothing would say so.
+ *
+ * A version too large for one variable names others under `refs`: a module's
+ * Source (JSON) or a file's text, each in a variable of its own --
+ * `{ "refs": { "modules": { "/a.val.ts": "env://VAL_CONTENT_1" } } }`. Flat:
+ * a referenced variable holds the value itself and is never read for further
+ * references. Only `refs` is resolved, never a string inside Source, and only
+ * `VAL_CONTENT_<n>` is ever read: Source is text editors write, and a
+ * reference resolved in there would read any variable the isolate holds,
+ * `VAL_SECRET` included, into a page. The scheme leaves room for another
+ * place to read from; one this does not know is refused, not skipped.
+ */
+export declare function contentFromEnv(env: Record<string, string | undefined>): ValContentVersion | undefined;
+/**
+ * What a server or reader renders over the bundle: a proposal's saves over the
+ * content version the site serves, either alone, or nothing.
+ *
+ * Layered rather than chosen. At a proposal's address the platform hands both
+ * when the base the proposal was opened from serves content its build does not
+ * bundle (a content-only publish), and the proposal saves only the modules it
+ * changed: choosing the proposal alone would show every other module as the
+ * build bundles it -- older than the site it was opened from.
+ */
+export declare function layeredSnapshot(proposal: Pick<ValProposal, "modules" | "files"> | undefined, contentVersion: Pick<ValContentVersion, "modules" | "files"> | undefined): Pick<ValProposal, "modules" | "files"> | undefined;
 /**
  * The proposal's saved Source, as Source: every module whose value is JSON.
  * One place, so the server and the readers that render without it agree on

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

@@ -3636,6 +3636,13 @@ class ValOps {
    * {@link siteSourcesUnderSnapshot}, and only where there is a snapshot.
    */
   siteSourcesBeforeSnapshot = null;
+  /**
+   * The same modules as the bundle evaluated them, imports and all: where a
+   * `.jsonValues()` entry the snapshot did not save is read from. Not
+   * {@link siteSourcesBeforeSnapshot}, whose markers may have come as JSON
+   * from a content version, with no import behind them.
+   */
+  bundleSourcesBeforeSnapshot = null;
   /**
    * What a save has told us each `.jsonValues()` entry now holds.
    *
@@ -3694,7 +3701,7 @@ class ValOps {
   // #region initTree
   async initSources() {
     if (this.baseSha === null || this.sourcesSha === null || this.configSha === null || this.schemaSha === null || this.sources === null || this.schemas === null || this.modulesErrors === null) {
-      var _this$options;
+      var _this$options, _this$options2;
       const extracted = await core.extractValModules(this.valModules);
       const moduleErrors = extracted.moduleErrors.concat(findNestedJsonValuesModuleErrors(extracted.schemas));
       this.sources = extracted.sources;
@@ -3712,16 +3719,45 @@ class ValOps {
        * being served, and a base SHA that still described the bundle would
        * say the snapshot's content was the bundle's.
        */
-      if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.snapshotSources) {
+      const siteLayer = (_this$options = this.options) === null || _this$options === void 0 ? void 0 : _this$options.siteSnapshotSources;
+      const snapshotLayer = (_this$options2 = this.options) === null || _this$options2 === void 0 ? void 0 : _this$options2.snapshotSources;
+      /*
+       * The bundle's own Source for every module either layer replaces: a
+       * replaced `.jsonValues()` module's markers came as JSON, and an entry
+       * neither layer saved is read through the bundle's marker, which still
+       * has its `import()`.
+       */
+      if (siteLayer || snapshotLayer) {
+        const bundle = {};
+        for (const moduleFilePath of Object.keys({
+          ...siteLayer,
+          ...snapshotLayer
+        })) {
+          const path = moduleFilePath;
+          const bundled = extracted.sources[path];
+          if (bundled !== undefined) {
+            bundle[path] = bundled;
+          }
+        }
+        this.bundleSourcesBeforeSnapshot = bundle;
+      }
+      // What a proposal is compared against: the site, only where there is a proposal.
+      if (snapshotLayer) {
         const site = {};
-        for (const moduleFilePath of Object.keys(this.options.snapshotSources)) {
-          const source = extracted.sources[moduleFilePath];
+        for (const moduleFilePath of Object.keys(snapshotLayer)) {
+          const path = moduleFilePath;
+          const source = (siteLayer === null || siteLayer === void 0 ? void 0 : siteLayer[path]) ?? extracted.sources[path];
           if (source !== undefined) {
-            site[moduleFilePath] = source;
+            site[path] = source;
           }
         }
         this.siteSourcesBeforeSnapshot = site;
-        this.promoteCommittedSources(this.options.snapshotSources);
+      }
+      if (siteLayer || snapshotLayer) {
+        this.promoteCommittedSources({
+          ...siteLayer,
+          ...snapshotLayer
+        });
       }
       return {
         baseSha: this.baseSha,
@@ -3751,8 +3787,8 @@ class ValOps {
    * both, so it is not sent. `null` anywhere that is not a proposal.
    */
   async siteSourcesUnderSnapshot() {
-    var _this$options2;
-    if (!((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.snapshotSources)) return null;
+    var _this$options3;
+    if (!((_this$options3 = this.options) !== null && _this$options3 !== void 0 && _this$options3.snapshotSources)) return null;
     await this.initSources();
     return this.siteSourcesBeforeSnapshot;
   }
@@ -4059,7 +4095,7 @@ class ValOps {
       }
     }
     const loaded = await Promise.all([...requestedKeys, ...sourceKeys].map(async entryKey => {
-      var _this$adoptedJsonEntr, _this$siteSourcesBefo;
+      var _this$adoptedJsonEntr, _this$bundleSourcesBe;
       const marker = record[entryKey];
       if (marker !== undefined && !core.Internal.isJson(marker)) {
         // Not a jsonValues entry — return the inlined value as-is (defensive).
@@ -4106,7 +4142,7 @@ class ValOps {
        * entry the proposal did not save is the build's, behind the marker
        * the module evaluated to.
        */
-      const siteMarker = (_this$siteSourcesBefo = this.siteSourcesBeforeSnapshot) === null || _this$siteSourcesBefo === void 0 || (_this$siteSourcesBefo = _this$siteSourcesBefo[moduleFilePath]) === null || _this$siteSourcesBefo === void 0 ? void 0 : _this$siteSourcesBefo[entryKey];
+      const siteMarker = (_this$bundleSourcesBe = this.bundleSourcesBeforeSnapshot) === null || _this$bundleSourcesBe === void 0 || (_this$bundleSourcesBe = _this$bundleSourcesBe[moduleFilePath]) === null || _this$bundleSourcesBe === void 0 ? void 0 : _this$bundleSourcesBe[entryKey];
       const thunk = core.Internal.getJsonImport(marker) ?? (core.Internal.isJson(siteMarker) ? core.Internal.getJsonImport(siteMarker) : undefined);
       if (!thunk) {
         return {
@@ -5365,9 +5401,9 @@ class ValOps {
         // https://github.com/microsoft/TypeScript/issues/36174
         let sourceFileText = null;
         if (tsChanged) {
-          var _this$options3;
+          var _this$options4;
           sourceFileText = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
-          if ((_this$options3 = this.options) !== null && _this$options3 !== void 0 && _this$options3.formatter) {
+          if ((_this$options4 = this.options) !== null && _this$options4 !== void 0 && _this$options4.formatter) {
             try {
               sourceFileText = await this.options.formatter(sourceFileText, path);
             } catch (err) {
@@ -5379,13 +5415,13 @@ class ValOps {
         }
         const extraFiles = {};
         for (const [jsonPath, content] of Array.from(jsonEntryContents)) {
-          var _this$options4;
+          var _this$options5;
           if (content === null) {
             extraFiles[jsonPath] = null;
             continue;
           }
           let jsonText = JSON.stringify(content, null, 2);
-          if ((_this$options4 = this.options) !== null && _this$options4 !== void 0 && _this$options4.formatter) {
+          if ((_this$options5 = this.options) !== null && _this$options5 !== void 0 && _this$options5.formatter) {
             try {
               jsonText = await this.options.formatter(jsonText, jsonPath);
             } catch (err) {
@@ -9004,6 +9040,182 @@ function proposalFromEnv(env) {
   };
 }
 
+/**
+ * A content version: the site's content, served by a build that bundles an
+ * older one. valbuild/home `docs/hosted-publishing.md`, step 2.
+ *
+ * The platform hands over only what differs from the bundle -- the modules
+ * whose Source changed and the Val files whose text did -- the way it hands a
+ * proposal's address its saved content, and it is read the same way: the
+ * snapshot source provider, over the bundle. What differs is the position: a
+ * version names the publish that made it (`job`, or its `commit`), and that is
+ * where this server says it sits, never at the build it runs in.
+ */
+
+/**
+ * The content version a platform hands over in its runtime env
+ * (`VAL_CONTENT`), or `undefined` when it hands over none.
+ *
+ * Throws on one it cannot read rather than serving the bundle as though it
+ * were the version: the site would show content older than what was
+ * published, and nothing would say so.
+ *
+ * A version too large for one variable names others under `refs`: a module's
+ * Source (JSON) or a file's text, each in a variable of its own --
+ * `{ "refs": { "modules": { "/a.val.ts": "env://VAL_CONTENT_1" } } }`. Flat:
+ * a referenced variable holds the value itself and is never read for further
+ * references. Only `refs` is resolved, never a string inside Source, and only
+ * `VAL_CONTENT_<n>` is ever read: Source is text editors write, and a
+ * reference resolved in there would read any variable the isolate holds,
+ * `VAL_SECRET` included, into a page. The scheme leaves room for another
+ * place to read from; one this does not know is refused, not skipped.
+ */
+function contentFromEnv(env) {
+  if (!env.VAL_CONTENT) {
+    return undefined;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(env.VAL_CONTENT);
+  } catch (err) {
+    throw new Error(`Val: VAL_CONTENT is not JSON (${err instanceof Error ? err.message : String(err)})`, {
+      cause: err
+    });
+  }
+  if (!isObject$1(parsed) || Array.isArray(parsed)) {
+    throw new Error("Val: VAL_CONTENT is not an object");
+  }
+  const id = parsed["id"];
+  if (typeof id !== "string" || id === "") {
+    throw new Error("Val: VAL_CONTENT has no id");
+  }
+  const job = parsed["job"] ?? null;
+  const commit = parsed["commit"] ?? null;
+  if (job !== null && typeof job !== "string") {
+    throw new Error(`Val: content version ${id}: job must be a string or null`);
+  }
+  if (commit !== null && typeof commit !== "string") {
+    throw new Error(`Val: content version ${id}: commit must be a string or null`);
+  }
+  const modulesIn = parsed["modules"] ?? {};
+  const filesIn = parsed["files"] ?? {};
+  if (!isObject$1(modulesIn) || Array.isArray(modulesIn) || !isObject$1(filesIn) || Array.isArray(filesIn)) {
+    throw new Error(`Val: content version ${id}: modules and files must be objects`);
+  }
+  const files = {};
+  for (const [path, text] of Object.entries(filesIn)) {
+    if (typeof text === "string") {
+      files[path] = text;
+    }
+  }
+  const modules = {
+    ...modulesIn
+  };
+  const refs = parsed["refs"] ?? {};
+  if (!isObject$1(refs) || Array.isArray(refs)) {
+    throw new Error(`Val: content version ${id}: refs must be an object`);
+  }
+  const read = (kind, path, ref) => {
+    const where = `Val: content version ${id}: refs.${kind}["${path}"]`;
+    if (typeof ref !== "string") {
+      throw new Error(`${where} must be a string`);
+    }
+    if (!ref.startsWith(ENV_REF)) {
+      throw new Error(`${where} is ${ref}: only ${ENV_REF}VAL_CONTENT_<n> is read`);
+    }
+    const name = ref.slice(ENV_REF.length);
+    if (!CONTENT_VARIABLE.test(name)) {
+      throw new Error(`${where} names ${name}: only VAL_CONTENT_<n> is read`);
+    }
+    const value = env[name];
+    if (value === undefined) {
+      throw new Error(`${where} names ${name}, which is not set`);
+    }
+    return {
+      where,
+      name,
+      value
+    };
+  };
+  const refModules = refs["modules"] ?? {};
+  const refFiles = refs["files"] ?? {};
+  if (!isObject$1(refModules) || Array.isArray(refModules) || !isObject$1(refFiles) || Array.isArray(refFiles)) {
+    throw new Error(`Val: content version ${id}: refs.modules and refs.files must be objects`);
+  }
+  for (const [path, ref] of Object.entries(refModules)) {
+    const {
+      where,
+      name,
+      value
+    } = read("modules", path, ref);
+    if (Object.prototype.hasOwnProperty.call(modules, path)) {
+      throw new Error(`${where}: ${path} is also in modules`);
+    }
+    try {
+      modules[path] = JSON.parse(value);
+    } catch (err) {
+      throw new Error(`${where}: ${name} is not JSON (${err instanceof Error ? err.message : String(err)})`, {
+        cause: err
+      });
+    }
+  }
+  for (const [path, ref] of Object.entries(refFiles)) {
+    const {
+      where,
+      value
+    } = read("files", path, ref);
+    // The handed object, not `files`: an inline value that is not text was
+    // dropped from `files`, and is still a second naming of the path.
+    if (Object.prototype.hasOwnProperty.call(filesIn, path)) {
+      throw new Error(`${where}: ${path} is also in files`);
+    }
+    files[path] = value;
+  }
+  if (job === null && commit === null) {
+    // Placed nowhere, Val would place it at the build it runs in -- the one
+    // position a version must never take: its own changes would be replayed
+    // over a snapshot that already holds them.
+    throw new Error(`Val: content version ${id} must name a job or a commit, or it would be placed at the build it runs in`);
+  }
+  return {
+    id,
+    job,
+    commit,
+    modules,
+    files
+  };
+}
+
+/** The one scheme a content version's `refs` may use, for now. */
+const ENV_REF = "env://";
+/** The only variables a reference may name. */
+const CONTENT_VARIABLE = /^VAL_CONTENT_[0-9]+$/;
+
+/**
+ * What a server or reader renders over the bundle: a proposal's saves over the
+ * content version the site serves, either alone, or nothing.
+ *
+ * Layered rather than chosen. At a proposal's address the platform hands both
+ * when the base the proposal was opened from serves content its build does not
+ * bundle (a content-only publish), and the proposal saves only the modules it
+ * changed: choosing the proposal alone would show every other module as the
+ * build bundles it -- older than the site it was opened from.
+ */
+function layeredSnapshot(proposal, contentVersion) {
+  if (proposal === undefined) return contentVersion;
+  if (contentVersion === undefined) return proposal;
+  return {
+    modules: {
+      ...contentVersion.modules,
+      ...proposal.modules
+    },
+    files: {
+      ...contentVersion.files,
+      ...proposal.files
+    }
+  };
+}
+
 /**
  * The proposal's saved Source, as Source: every module whose value is JSON.
  * One place, so the server and the readers that render without it agree on
@@ -9498,6 +9710,8 @@ class ValOpsHttp extends ValOps {
   publishBuild;
   /** See `proposal` on {@link ValApiOptions}; `null` on the site. */
   proposal;
+  /** See `contentVersion` on {@link ValApiOptions}; `null` at a proposal's address. */
+  contentVersion;
 
   /** Did the host hand over the running build's source? See `projectSource`. */
   embedsSource() {
@@ -9570,10 +9784,22 @@ class ValOpsHttp extends ValOps {
    * getSettings / uploadRemoteFile / getPresignedAuthNonce.
    */
   auth, valModules, options) {
-    super(valModules, options !== null && options !== void 0 && options.proposal ? {
+    /*
+     * What replaces the bundle's Source: the content version the site serves,
+     * and a proposal's saves over it at its address. Two layers rather than
+     * one, because the version is the SITE -- what a proposal is compared
+     * against -- and the proposal is what is being proposed.
+     */
+    const snapshot = layeredSnapshot(options === null || options === void 0 ? void 0 : options.proposal, options === null || options === void 0 ? void 0 : options.contentVersion);
+    super(valModules, options && snapshot ? {
       ...options,
-      snapshotSources: proposalSnapshot(options.proposal),
-      snapshotJsonEntries: proposalJsonEntries(options.proposal, options.projectSource)
+      ...(options.proposal !== undefined ? {
+        snapshotSources: proposalSnapshot(options.proposal)
+      } : {}),
+      ...(options.contentVersion !== undefined ? {
+        siteSnapshotSources: proposalSnapshot(options.contentVersion)
+      } : {}),
+      snapshotJsonEntries: proposalJsonEntries(snapshot, options.projectSource)
     } : options);
     this.contentUrl = contentUrl;
     this.project = project;
@@ -9585,16 +9811,25 @@ class ValOpsHttp extends ValOps {
     };
     this.root = (options === null || options === void 0 ? void 0 : options.root) ?? "";
     this.proposal = (options === null || options === void 0 ? void 0 : options.proposal) ?? null;
+    this.contentVersion = this.proposal === null ? (options === null || options === void 0 ? void 0 : options.contentVersion) ?? null : null;
     /*
      * In a proposal, the text its saves wrote over the text the build was made
      * from: the next save patches the last one's `.val.ts`, not the base's.
+     * The same for a content version: the next publish patches what the last
+     * one published, not what the build bundles.
      */
-    this.projectSource = this.proposal !== null ? {
+    this.projectSource = snapshot !== undefined ? {
       ...((options === null || options === void 0 ? void 0 : options.projectSource) ?? {}),
-      ...this.proposal.files
+      ...snapshot.files
     } : (options === null || options === void 0 ? void 0 : options.projectSource) ?? null;
     this.publishJob = (options === null || options === void 0 ? void 0 : options.publishJob) ?? null;
-    this.publishBuild = (options === null || options === void 0 ? void 0 : options.publishBuild) ?? null;
+    /*
+     * Not with a content version: the content service places a build by the
+     * build first (`getApplicablePatchesAndCommits`), and this build bundles an
+     * older version than it serves -- placed there, the version's own changes
+     * would be replayed over a snapshot that already holds them.
+     */
+    this.publishBuild = this.contentVersion === null ? (options === null || options === void 0 ? void 0 : options.publishBuild) ?? null : null;
     this.mirrorsSourceFiles = git !== null || this.projectSource !== null;
   }
   /**
@@ -10268,6 +10503,22 @@ class ValOpsHttp extends ValOps {
         } : {})
       };
     }
+    /*
+     * A content version sits where the publish that made it does: its job,
+     * which content places exactly, or its commit, once nothing else says.
+     */
+    if (this.contentVersion !== null) {
+      if (this.contentVersion.job !== null) {
+        return {
+          job: this.contentVersion.job
+        };
+      }
+      if (this.contentVersion.commit !== null) {
+        return {
+          commit: this.contentVersion.commit
+        };
+      }
+    }
     if (this.git) {
       return {
         branch: this.git.branch,
@@ -13528,6 +13779,9 @@ async function initHandlerOptions(route, opts, config) {
       ...(opts.proposal !== undefined ? {
         proposal: opts.proposal
       } : {}),
+      ...(opts.contentVersion !== undefined ? {
+        contentVersion: opts.contentVersion
+      } : {}),
       project: maybeValProject,
       valEnableRedirectUrl,
       valDisableRedirectUrl,
@@ -13606,6 +13860,9 @@ function createValOps(valModules, options) {
       } : {}),
       ...(options.proposal !== undefined ? {
         proposal: options.proposal
+      } : {}),
+      ...(options.contentVersion !== undefined ? {
+        contentVersion: options.contentVersion
       } : {})
     });
   }
@@ -24102,6 +24359,7 @@ exports.awaitValLoginConfirmation = awaitValLoginConfirmation;
 exports.checkRemoteRef = checkRemoteRef;
 exports.classifyJsonValuesOp = classifyJsonValuesOp;
 exports.compareWithCapturedReport = compareWithCapturedReport;
+exports.contentFromEnv = contentFromEnv;
 exports.createDefaultValFSHost = createDefaultValFSHost;
 exports.createFixPatch = createFixPatch;
 exports.createJsonEntryPathMap = createJsonEntryPathMap;
@@ -24157,6 +24415,7 @@ exports.handleVideosetMetadata = handleVideosetMetadata;
 exports.handleVideosetUploadRemote = handleVideosetUploadRemote;
 exports.initHandlerOptions = initHandlerOptions;
 exports.isExternalResult = isExternalResult;
+exports.layeredSnapshot = layeredSnapshot;
 exports.loadValModules = loadValModules;
 exports.ok = ok;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;