@valbuild/shared 0.150.20 → 0.152.0

package/dist/declarations/src/internal/content/moduleStore.d.ts

@@ -0,0 +1,119 @@
+import type { Json, ModuleFilePath, PatchId } from "@valbuild/core";
+import { type ModuleContent } from "./applyChain.js";
+import { type ModuleVersion } from "./version.js";
+/** One module's content at one version, as a tier holds it. */
+export type StoredModule = {
+    readonly path: ModuleFilePath;
+    readonly version: ModuleVersion;
+    readonly content: ModuleContent;
+    /**
+     * The patch ids the version's chain is made of, in chain order: empty for a
+     * base. What a newer version of the same chain is extended from, and what a
+     * delta between two versions is made of.
+     */
+    readonly patches: readonly PatchId[];
+    /**
+     * What holding this costs beyond what is held anyway: the containers the
+     * engine copied and the values the patches brought, never the base the
+     * build holds for every visitor. Zero for the bundle's own module.
+     */
+    readonly bytes: number;
+};
+export interface ModuleTier {
+    /** `memory`, `bundle`, `base`, `origin`: goes into counted work and test frames. */
+    readonly name: string;
+    get(key: string): StoredModule | null | Promise<StoredModule | null>;
+    put?(key: string, value: StoredModule, bytes: number): void;
+}
+/**
+ * What the stores in this process have answered, by tier, and how often
+ * none of them had a key: a test takes it before and after. Never reset.
+ */
+export declare function storeWork(): {
+    hits: Readonly<Record<string, number>>;
+    misses: number;
+};
+/**
+ * Asks each tier in turn; what a slower tier answers is written to the faster
+ * ones before it. A tier that answers `null` has no say.
+ */
+export declare function tiered(tiers: readonly ModuleTier[]): ModuleTier;
+export type MemoryTier = ModuleTier & {
+    put(key: string, value: StoredModule, bytes: number): void;
+    /**
+     * The newest version held of a module, whatever its key: what the next
+     * version of the same chain is extended from rather than replayed.
+     */
+    latest(path: ModuleFilePath): StoredModule | null;
+    /** What it holds now. */
+    stats(): MemoryTierStats;
+    /**
+     * Charge a held key for something added to it after it was put (an entry
+     * resolved on it), so the budget sees it.
+     */
+    charge(key: string, bytes: number): void;
+};
+export type MemoryTierStats = {
+    /** Bytes held, by the measure each value was put with. */
+    bytes: number;
+    /** Versions held: values a chain made (not bases written up from a slower tier). */
+    versions: number;
+    /** Modules with at least one version held. */
+    modules: number;
+    /** The most versions held of any one module. */
+    mostVersionsOfOneModule: number;
+    /** The most bytes held for any one module, all its versions together. */
+    mostBytesOfOneModule: number;
+    /** Values let go so far, for the budget or the ring. */
+    evicted: number;
+};
+/**
+ * Bounded by bytes; keeps the last `lastPerModule` versions per module path
+ * (and, apart from them, the last `lastPerModule` bases), and lets go of the least recently read value when over `budgetBytes`. A
+ * value bigger than the whole budget is still held while it is the newest,
+ * so the read that made it is answered; the next put lets it go.
+ */
+export declare function memoryTier(opts: {
+    budgetBytes: number;
+    lastPerModule: number;
+    name?: string;
+}): MemoryTier;
+/**
+ * The build's own modules, free: answers only a key whose version is the
+ * bundle's -- its schema, its base and the empty chain -- with the bundle's
+ * own object, which the process holds for every visitor anyway. `bundle`
+ * says what the build evaluated each module to; `null` for a module the
+ * build does not have.
+ */
+export declare function bundleTier(bundle: (path: ModuleFilePath) => {
+    version: ModuleVersion;
+    source: Json;
+} | null | Promise<{
+    version: ModuleVersion;
+    source: Json;
+} | null>, name?: string): ModuleTier;
+/** The module a {@link moduleKey} is the address of, or `null` for none. */
+export declare function pathOfModuleKey(key: string): ModuleFilePath | null;
+/**
+ * The version a {@link moduleKey} names, or `null` when it is not one. The
+ * three parts are hex or empty, so the split is unambiguous.
+ */
+export declare function parseModuleKey(key: string): {
+    path: ModuleFilePath;
+    version: ModuleVersion;
+} | null;
+/**
+ * A `.jsonValues()` entry's version: the record's schema and base, the
+ * entry's key, and the chain of the record's patches that touched THIS
+ * entry -- so an entry no patch touched keeps its version while the record's
+ * chain grows, and two reads at one entry version are the same content.
+ * Entries are stored on their own, so a large record is not copied because
+ * one entry changed.
+ */
+export type EntryVersion = ModuleVersion & {
+    key: string;
+};
+/** The address of an entry's content. Never changes meaning. */
+export declare function entryAddress(path: ModuleFilePath, v: EntryVersion): string;
+/** Whether two entry versions name the same content. */
+export declare function sameEntryVersion(a: EntryVersion, b: EntryVersion): boolean;

package/dist/declarations/src/internal/content/source.d.ts

@@ -0,0 +1,71 @@
+import type { Json, ModuleFilePath } from "@valbuild/core";
+import type { ModuleVersion } from "./version.js";
+import type { EntryVersion } from "./moduleStore.js";
+/**
+ * Where a reader's content comes from, in one shape: see
+ * `docs/plans/one-content-model.md`, "One way to load". Every reader --
+ * `fetchVal` on the server, `useVal` in the browser, and (phase 5) the
+ * Studio -- asks a list of these, and only the list differs between them.
+ *
+ * Types only, here, because the sources are written on both sides of a
+ * package line: the browser's (`@valbuild/react`) and the server's
+ * (`@valbuild/server`, which cannot import React's package), and the one
+ * rule that picks between them (`layered`) has to read both.
+ */
+/** What a source says about one module. */
+export type ModuleRead = {
+    status: "ready";
+    source: Json;
+    /** Which source answered: goes into a reader's reads, and test frames. */
+    from: string;
+    /** The version of what it answered, where the source carries one. */
+    version: ModuleVersion | null;
+}
+/** No say here: ask the next source. */
+ | {
+    status: "pass";
+}
+/** Will have a say: wait for `ready`, then ask again. */
+ | {
+    status: "pending";
+    ready: Promise<void>;
+};
+/**
+ * What a source says about one `.jsonValues()` entry: the same as a module,
+ * plus `gone` -- an ANSWER, "this entry is not there" (a pending patch removed
+ * it), which is not the same as `pass`, "I cannot say". Collapsing the two is
+ * what once made a deleted entry keep rendering its published content.
+ */
+export type EntryRead = {
+    status: "ready";
+    content: unknown;
+    from: string;
+    /** The entry's own version, where the source carries one. */
+    version?: EntryVersion | null;
+} | {
+    status: "gone";
+    from: string;
+} | {
+    status: "pass";
+} | {
+    status: "pending";
+    ready: Promise<void>;
+}
+/** The source tried and could not: an entry's import that rejected. */
+ | {
+    status: "failed";
+    error: unknown;
+};
+export interface ContentSource {
+    /** `overlay`, `server-draft`, `snapshot`, `bundle`: what `from` says. */
+    readonly name: string;
+    module(path: ModuleFilePath): ModuleRead;
+    entry(path: ModuleFilePath, key: string): EntryRead;
+    /** Call `onChange` when a read of `paths` may answer differently. */
+    subscribe?(paths: readonly ModuleFilePath[], onChange: () => void): () => void;
+    /**
+     * A string that changes exactly when a read of `paths` would: what a hook
+     * hands `useSyncExternalStore`, compared with `===`.
+     */
+    revision?(paths: readonly ModuleFilePath[]): string;
+}

package/dist/declarations/src/internal/content/version.d.ts

@@ -0,0 +1,151 @@
+import { type ModuleFilePath, type PatchId } from "@valbuild/core";
+import { z } from "zod";
+/**
+ * What a module's content IS: the schema it is read and patched with, the
+ * base it starts from, and the chain of patches on top. Three parts because
+ * each kind of change moves exactly one of them (see
+ * `docs/plans/one-content-model.md`, "A version, per module, with the code in
+ * it"):
+ *
+ * - a schema change, or a new engine (`@valbuild/*` upgraded), moves `schema`;
+ * - a publish, a content version, a literal edited in code, moves `base`;
+ * - an edit, a discard, a publish (which empties the chain) moves `chain`.
+ *
+ * Two answers with the same version are the same content, wherever they came
+ * from. That is the whole point: comparing contents becomes comparing three
+ * strings.
+ *
+ * Computed when content CHANGES -- a module evaluated, a base adopted, a patch
+ * appended -- never when it is read (risk 3 in the plan): every function here
+ * that hashes counts itself ({@link versionHashCount}), so a reader that
+ * hashes is caught by a counted budget rather than by a profile.
+ */
+export type ModuleVersion = {
+    /** sha(engine + serialized schema): what the content is read and patched with. */
+    schema: string;
+    /** sha(the module's base source): from the build, a content version or a publish. */
+    base: string;
+    /**
+     * A fold of this module's patch ids on top of `base`, in chain order: the
+     * IDENTITY of the chain, not its order -- that is `seq`. {@link EMPTY_CHAIN}
+     * for no patches, so a base is a version with an empty chain.
+     */
+    chain: string;
+};
+/**
+ * What a project answer is relative to: which build served it, and how far
+ * along the project's changes it is.
+ */
+export type ProjectVersion = {
+    /**
+     * The build serving it: the evaluated modules (schemas, sources and config)
+     * it started from, so two processes running the same code agree. Hosted,
+     * the commit or the platform's build (`publishBuild`) is part of it.
+     */
+    build: string;
+    /**
+     * ORDER only: bumped by every write, delete and publish, and once by each
+     * new build. Of two answers, the one with the higher `seq` is newer. In
+     * http mode it is the content service's `headVersion`.
+     */
+    seq: number;
+};
+/**
+ * What the schema version of a module staged after the build serving a
+ * proposal starts with: `staged:<inputs>`. Val's server has not got that
+ * module's schema, so it names the staging instead; a Studio compares no
+ * build's code against it.
+ */
+export declare const STAGED_SCHEMA_PREFIX = "staged:";
+/** The chain of no patches. */
+export declare const EMPTY_CHAIN = "";
+/**
+ * The engine: how patches are applied and content is read. Part of every
+ * schema version, because content read by another engine is not the same
+ * content even under the same schema.
+ */
+export declare const ENGINE: string;
+/**
+ * How many times a version has been hashed in this process: the counted
+ * budget behind "versions are computed when content changes, never when it
+ * is read" (`version:hash`). A test takes it before and after a read.
+ */
+export declare function versionHashCount(): number;
+/** A chain one patch longer. */
+export declare function extendChain(prev: string, id: PatchId): string;
+/** The chain of these patch ids, in order, on top of a base. */
+export declare function chainOf(ids: readonly PatchId[]): string;
+/**
+ * A module's schema version, from its serialized schema. The same function
+ * on the server (from what `extractValModules` serialized) and in the Studio
+ * (from what it holds in `SchemaStore`), so the two compare.
+ */
+export declare function schemaVersionOf(serializedSchema: unknown): string;
+/**
+ * A module's base version, from its base source: what the module evaluates
+ * to, or what a content version or a publish put in its place. `.jsonValues()`
+ * entries are markers here; an entry's own version comes with entries stored
+ * as modules of their own (phase 6).
+ */
+export declare function baseVersionOf(source: unknown): string;
+/** The address of a module's content. Never changes meaning. */
+export declare function moduleKey(path: ModuleFilePath, v: ModuleVersion): string;
+/** Whether two versions name the same content. */
+export declare function sameModuleVersion(a: ModuleVersion, b: ModuleVersion): boolean;
+/**
+ * The chains of every module, from the patches a draft applies (in chain
+ * order), folded incrementally.
+ *
+ * A read asks for the chains every time; the fold is extended only by the
+ * patches the chain has gained since the last call, and a call that finds the
+ * chain as it was hashes nothing. A chain that changed anywhere but at its end
+ * (a discard in the middle, a publish) is folded again from the start --
+ * once, when that is first noticed.
+ */
+export declare class ChainFold {
+    private ids;
+    private paths;
+    private chains;
+    /**
+     * Every module's chain after each of its patches, in order: what
+     * {@link chainAt} answers for a module whose content stopped part way
+     * along its chain (a patch that does not apply). Kept as the chains are
+     * extended, so asking hashes nothing.
+     */
+    private prefixes;
+    /**
+     * Bumped whenever the chains move: a cheap identity for "the same chains as
+     * before", in-process. With {@link instance} in front, two folds never name
+     * one epoch: two processes (or isolates) holding the same chains answer
+     * differently, which only costs a cache a miss, where two holding
+     * DIFFERENT chains at the same count must never answer alike (an ETag
+     * answered 304 for content the caller does not have).
+     */
+    private epochValue;
+    private readonly instance;
+    /** Every module's chain, for these patches. Modules with none are absent. */
+    chainsOf(patches: readonly {
+        patchId: PatchId;
+        path: ModuleFilePath;
+    }[]): ReadonlyMap<ModuleFilePath, string>;
+    /**
+     * A module's chain after its first `count` patches, of those the last
+     * {@link chainsOf} was given: the version of content that stopped at a
+     * patch that does not apply, so the version names the chain the content
+     * is AT. Hashes nothing.
+     */
+    chainAt(path: ModuleFilePath, count: number): string;
+    /** See {@link epochValue}. */
+    epoch(): string;
+}
+/** {@link ModuleVersion} on the wire. */
+export declare const ModuleVersionSchema: z.ZodObject<{
+    schema: z.ZodString;
+    base: z.ZodString;
+    chain: z.ZodString;
+}, z.core.$strip>;
+/** {@link ProjectVersion} on the wire. */
+export declare const ProjectVersionSchema: z.ZodObject<{
+    build: z.ZodString;
+    seq: z.ZodNumber;
+}, z.core.$strip>;

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

@@ -1,14 +1,20 @@
 export * from "./richtext/conversion/index.js";
 export * from "./richtext/richTextImages.js";
 export * from "./server/types.js";
-export * from "./server/requestScopedMemo.js";
 export * from "./ValClient.js";
 export * from "./demo.js";
 export * from "./ValUrls.js";
 export * from "./ApiRoutes.js";
+export * from "./valClientHeader.js";
 export * from "./schema/compatibility.js";
 export * from "./newestCommitSha.js";
 export * from "./chainHead.js";
+export * from "./content/version.js";
+export * from "./content/buildRegistry.js";
+export * from "./content/applyChain.js";
+export * from "./content/jsonValuesOps.js";
+export * from "./content/moduleStore.js";
+export type * from "./content/source.js";
 export * from "./zod/Patch.js";
 export * from "./sessionStorage.js";
 export * from "./SharedValConfig.js";
@@ -46,6 +52,7 @@ export * from "./search/sourcePath.js";
 export * from "./theme/accentRamp.js";
 export * from "./publish/contentApi.js";
 export * from "./publish/protocol.js";
+export * from "./publish/projectSource.js";
 export * from "./patchSets/PatchSets.js";
 export * from "./patchSets/selectionClosure.js";
 export * from "./patchSets/schemaTypesOfPath.js";

package/dist/declarations/src/internal/publish/projectSource.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where content's publish API is reached: through Val's proxy on this origin
+ * (`api`, the Studio), or directly (`publishApi`, `<content>/v1`: home's
+ * upgrade page, whose `fetchImpl` adds the project token).
+ */
+export type PublishApiAt = {
+    /** Val's API root on this origin, e.g. `/api/val`. */
+    api: string;
+} | {
+    /** Content's publish API itself, e.g. `https://content.val.build/v1`. */
+    publishApi: string;
+};
+export declare function publishApiOf(at: PublishApiAt): string;
+/**
+ * The site's live source, BY VERSION: for a reader that asks again and again
+ * over a long life -- the Studio's code tools, on every tool call -- rather
+ * than once per deploy, as {@link createStudioPublishClient}'s memo does.
+ *
+ * Each call asks `/project-source` with the `ETag` of the answer it holds
+ * (`If-None-Match`), and content answers 304 while it is still that one
+ * (valbuild/home sends the tag: the sha256 of its answer). So a publish in
+ * between is seen on the next call, and the whole source is sent only when
+ * it changed. An answer without a tag (an older content service) is not
+ * held: every call reads it again, which is right, if dearer.
+ */
+export declare function createProjectSourceReader(options: PublishApiAt & {
+    fetchImpl?: typeof fetch;
+}): () => Promise<Record<string, string> | null>;

package/dist/declarations/src/internal/search/searchIndex.d.ts

@@ -57,6 +57,28 @@ export type SearchIndex = {
      * re-indexing one module exists to avoid.
      */
     docsByModule: Map<ModuleFilePath, Set<string>>;
+    /**
+     * For a module whose root is a record: each entry's documents, and the
+     * value they were made from, by key -- so indexing it again walks only the
+     * entries whose value is a different object (see {@link indexModule}).
+     */
+    /**
+     * What each module was last indexed from, whole: the same source object
+     * under a schema that says the same is not walked again. Removing a
+     * document from a big index is slow (FlexSearch looks for it everywhere),
+     * so indexing an unchanged module again was the cost of a pass.
+     */
+    walkedByModule: Map<ModuleFilePath, {
+        source: Json;
+        schema: string;
+    }>;
+    entriesByModule: Map<ModuleFilePath, {
+        schema: SerializedSchema;
+        entries: Map<string, {
+            source: Json;
+            docs: string[];
+        }>;
+    }>;
 };
 /** An index with nothing in it. Fill it with {@link indexModule}. */
 export declare function createSearchIndex(): SearchIndex;
@@ -70,10 +92,19 @@ export declare function createSearchIndex(): SearchIndex;
  * `.jsonValues()` entries are indexed only once their content is loaded — an
  * un-loaded entry is an opaque marker that {@link traverseSchemaSource} skips, so
  * the index is naturally PARTIAL and grows as batches land. That is why the search
- * UI loads the entries on the first query and re-indexes (debounced) as they
- * arrive, rather than pretending an empty result set is an answer.
+ * UI loads the entries on the first query and re-indexes as they arrive, rather
+ * than pretending an empty result set is an answer -- and why a module whose
+ * root is a record is re-indexed by entry ({@link indexRecordModule}): a pass
+ * per batch walks the batch, not the record.
+ */
+export declare function indexModule(searchIndex: SearchIndex, moduleFilePath: ModuleFilePath, source: Json, schema: SerializedSchema, 
+/**
+ * Stop by this time (`performance.now()`), for a caller that must not hold
+ * the thread: answers `false` when it stopped with entries of a record
+ * module still to walk, and the same call again goes on from there. A
+ * module that is not a record is walked whole, whatever the time.
  */
-export declare function indexModule(searchIndex: SearchIndex, moduleFilePath: ModuleFilePath, source: Json, schema: SerializedSchema): void;
+until?: number): boolean;
 /**
  * Drop everything indexed for one module.
  *

package/dist/declarations/src/internal/server/types.d.ts

@@ -45,7 +45,15 @@ export type ValServerJsonResult<Body extends Json | never = never, Error extends
     status: 400;
     json: Error;
 } : never);
-export type ValServerGenericResult = ValServerJsonResult<Json> | ValServerError | ValServerRedirectResult<ValCookiesNames> | ValServerResult<ValCookiesNames, string | ReadableStream<Uint8Array>>;
+/**
+ * Nothing moved since the ETag the caller sent back: no body, as HTTP
+ * requires of a 304.
+ */
+export type ValServerNotModified = {
+    status: 304;
+    headers?: Record<string, string | undefined>;
+};
+export type ValServerGenericResult = ValServerNotModified | ValServerJsonResult<Json> | ValServerError | ValServerRedirectResult<ValCookiesNames> | ValServerResult<ValCookiesNames, string | ReadableStream<Uint8Array>>;
 export type ValUIRequestHandler = (path: string, url: string) => Promise<ValServerGenericResult>;
 export type ValSession = {
     mode: "unauthorized";

package/dist/declarations/src/internal/sketchpad/sketchFormat.d.ts

@@ -2,18 +2,24 @@
  * A page sketch: a page written as indented text, with four primitives.
  *
  * ```
+ * --- /about                   a route: what follows is the page at /about
  * # Our people                 text (a heading: #, ## or ###)
  * We are 40 people in Oslo.    text (a paragraph)
+ * ## Hi {field: /x.val.ts?p="t"}  text linked to a content field: typing
+ *                              in it writes the field
  * [image: Team photo]          placeholder: [kind] or [kind: label]
  * [hero: Roof](image: /a.jpg)  a placeholder with an image (or video) in it
  * icon hero M3 5h18v14H3z      how every [hero] box is drawn: SVG path data
  * row                          its children side by side
- *   col 2                      its children stacked; 2 shares of the row
- *     ## Design
+ *   col                        its children stacked; columns share a row
+ *     ## Design                equally
  *   col
  *     [button: Join us]
  * ```
  *
+ * A sketchpad is not one page's: a route divider starts the part about a
+ * page, so one sketch can cover a page and the two it links to.
+ *
  * It is a scratch pad, not a layout language: it says WHAT is on a page and
  * roughly WHERE, so an assistant and a person can agree on a page's content
  * before anyone worries about how it looks. The person never sees this text,
@@ -31,17 +37,23 @@
  * image. Media put in a box is written into the text too, so the assistant
  * that builds the page reads it exactly as the person left it.
  */
-export type SketchNode = SketchRow | SketchCol | SketchText | SketchPlaceholder;
+export type SketchNode = SketchRoute | SketchRow | SketchCol | SketchText | SketchPlaceholder;
+/** The start of the part about one page. Only at the top level. */
+export type SketchRoute = {
+    type: "route";
+    line: number;
+    /** The page's route as the site serves it: `/about`, `/blog/[slug]`. */
+    route: string;
+};
 export type SketchRow = {
     type: "row";
     line: number;
     children: SketchNode[];
 };
+/** Columns share their row equally: a sketch says what, not how wide. */
 export type SketchCol = {
     type: "col";
     line: number;
-    /** Shares of the enclosing row this column takes. */
-    weight: number;
     children: SketchNode[];
 };
 export type SketchText = {
@@ -50,6 +62,13 @@ export type SketchText = {
     /** 0 is a paragraph; 1-3 are headings. */
     level: 0 | 1 | 2 | 3;
     text: string;
+    /**
+     * The content field this text is linked to, as a source path
+     * (`/content/home.val.ts?p="hero"."title"`): typing in the block writes
+     * the field. Written `{field: <source path>}` at the end of the line. One
+     * block per field: a second link to the same field is not one.
+     */
+    field?: string;
 };
 export type SketchPlaceholder = {
     type: "placeholder";
@@ -58,10 +77,18 @@ export type SketchPlaceholder = {
     label: string | null;
     media: SketchMedia | null;
 };
+/**
+ * `src` names a file the project has, never a guess: its `path` exactly as
+ * the content has it (`/public/val/hero.webp`, or its remote URL), or an
+ * image uploaded to the assistant's session, `session:<key>`. Which files
+ * those are is the Studio's to check; the text only holds the name.
+ */
 export type SketchMedia = {
     type: "image" | "video";
     src: string;
 };
+/** The prefix of a `src` that is an image in the assistant's session. */
+export declare const SESSION_MEDIA_PREFIX = "session:";
 export type SketchError = {
     /** 1-based, like an editor's gutter. */
     line: number;
@@ -82,7 +109,7 @@ export declare function parseSketch(source: string): ParsedSketch;
  * The line a text block is written as. Line breaks become spaces, and a
  * paragraph that would read as something else is kept as text with `\`.
  */
-export declare function formatSketchText(level: SketchText["level"], text: string): string;
+export declare function formatSketchText(level: SketchText["level"], text: string, field?: string): string;
 /** The line a placeholder is written as. */
 export declare function formatSketchBox(placeholder: Pick<SketchPlaceholder, "kind" | "label" | "media">): string;
 /**
@@ -95,6 +122,14 @@ export declare function formatSketchBox(placeholder: Pick<SketchPlaceholder, "ki
  * it is not on the page.
  */
 export declare function formatSketch(blocks: SketchNode[], icons: Record<string, string>): string;
+/**
+ * The text of every block linked to a field, by field: what the Studio
+ * writes to the content when a linked block changes. The first block wins,
+ * as `formatSketch` keeps only its link.
+ */
+export declare function sketchFieldTexts(blocks: SketchNode[]): Map<string, string>;
+/** The pages a sketch is about, in the order it gives them. */
+export declare function sketchRoutes(blocks: SketchNode[]): string[];
 /**
  * What a list names a sketch by: its first top-level heading, the biggest
  * one first. Null for a sketch with no heading, which a list then names by

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

@@ -93,6 +93,26 @@ export type ValCanvasPageMessage = {
     draftMode: boolean;
     /** The URL the frame ended up on, which a redirect may have changed. */
     url: string;
+    /**
+     * The modules the page holds a draft of: what its server read for this
+     * request (`<ValProvider draft>`). The studio sends each of them in its
+     * catch-up, pending or not, so a draft that stopped being the draft
+     * before the studio was there to say so -- discarded, published -- is
+     * replaced rather than kept. Absent from a page of the release before,
+     * and from a page that read no draft.
+     */
+    holds?: ModuleFilePath[];
+    /**
+     * The version the page holds each of {@link holds} at, where its draft
+     * says (`draftHoldsVersions`): the studio does not send one it would
+     * send at the same version -- the same content. Absent from a page of
+     * the release before, which is sent everything it holds, as before.
+     */
+    holdsVersions?: Partial<Record<ModuleFilePath, {
+        schema: string;
+        base: string;
+        chain: string;
+    }>>;
 } | {
     val: typeof VAL_CANVAS_MESSAGE;
     type: "elements";
@@ -257,8 +277,18 @@ export type ValCanvasStudioMessage = {
     /**
      * The whole module source. `unknown` because the page's own types are the
      * ones that give it meaning; nothing in between should be interpreting it.
+     *
+     * @deprecated A page of this release reads `read`; this is for a page
+     * of the release before. Goes in the release after the one that ships
+     * `read`, with the bridges' fallback that reads it: see
+     * "Release-delayed deletions" in `docs/plans/one-content-model.md`.
      */
     source: unknown;
+    /**
+     * The same module as a read (`ModuleRead`), which the page keeps as it
+     * is. Optional: a Studio from the release before sends `source` alone.
+     */
+    read?: unknown;
 } | {
     /**
      * Everything the studio holds has been sent.
@@ -276,6 +306,22 @@ export type ValCanvasStudioMessage = {
      */
     val: typeof VAL_CANVAS_MESSAGE;
     type: "sourcesSynced";
+} | {
+    /**
+     * The server holds the editor's changes up to this version (`seq`, the
+     * server's `ProjectVersion.seq`; `null` from a server that reports
+     * none). Sent once after `sourcesSynced`, then every time it moves.
+     *
+     * What the page re-reads its server-rendered content on (a loader, a
+     * server component): those only show an edit once the server has it,
+     * so a refresh sent when the edit was typed raced the write and came
+     * back without it -- which a ten second safety refresh used to catch.
+     * A bridge of the release before ignores it, as it ignores any type it
+     * does not know.
+     */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "confirmed";
+    seq: number | null;
 } | {
     /**
      * What colour to outline the page's content in.