@valbuild/shared 0.150.20 → 0.151.0

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

@@ -0,0 +1,124 @@
+import { type PatchId } from "@valbuild/core";
+import type { SerializedSchema } from "@valbuild/core";
+import { type Operation, type Patch, type ReadonlyJSONValue } from "@valbuild/core/patch";
+/** What one `.jsonValues()` entry is at a point in a module's chain. */
+export type EntryState = 
+/** Its content, known. */
+{
+    kind: "content";
+    content: ReadonlyJSONValue;
+}
+/**
+ * The content of the BASE entry `from` (its own key, or the one it was
+ * moved or copied from), with `ops` on top: an entry nobody has loaded,
+ * whose edits are held until somebody does ({@link resolveEntry}).
+ */
+ | {
+    kind: "waiting";
+    from: string;
+    ops: HeldOps | null;
+}
+/** Removed, or moved away. */
+ | {
+    kind: "deleted";
+}
+/** An op on it could not be applied. Sticky, as a module's failure is. */
+ | {
+    kind: "error";
+    patchId: PatchId;
+    message: string;
+};
+/**
+ * The ops held for an entry, newest first: a list that is extended without
+ * copying, so a chain of N edits to an entry nobody loaded costs N, not N².
+ */
+export type HeldOps = {
+    readonly op: Operation;
+    readonly patchId: PatchId;
+    readonly before: HeldOps | null;
+};
+/**
+ * A module's content: its source, and what its `.jsonValues()` entries are.
+ *
+ * `entries` holds only the entries the chain has touched. An entry it has
+ * not is the base's: `waiting` on its own key with nothing held, as long as
+ * the source has its marker ({@link entryState}). So a module with no
+ * entries, or a chain that never touches one, costs nothing here.
+ */
+export type ModuleContent = {
+    readonly source: ReadonlyJSONValue;
+    readonly entries: ReadonlyMap<string, EntryState>;
+};
+/** One patch of a module's chain. */
+export type PatchRecord = {
+    readonly patchId: PatchId;
+    readonly patch: Patch;
+};
+export type PatchRecordResult = {
+    status: "applied";
+    module: ModuleContent;
+} | {
+    status: "failed";
+    patchId: PatchId;
+    message: string;
+};
+/** A module's content with nothing applied yet: its base. */
+export declare function baseModuleContent(source: ReadonlyJSONValue): ModuleContent;
+/**
+ * The work the engine has done in this process: patches applied
+ * (`engine:apply-patch`) and bytes copied (`engine:clone-bytes`, see
+ * {@link SLOT_BYTES}). A test takes it before and after; never reset, so two
+ * readers of it cannot disturb each other.
+ */
+export declare function engineWork(): {
+    applyPatch: number;
+    cloneBytes: number;
+};
+/**
+ * Applies one patch to a module's content. Nothing is mutated: the module
+ * passed in is still what it was, and the one returned shares every subtree
+ * the patch did not touch.
+ *
+ * `failed` means the patch does not apply, and then none of it does: half a
+ * patch is half an edit. The caller stops the module's chain there.
+ *
+ * `schema` is the module's serialized schema: it says which ops reach into a
+ * `.jsonValues()` entry. Without one, every op is an op on the source.
+ */
+export declare function applyPatchRecord(module: ModuleContent, record: PatchRecord, schema: SerializedSchema | undefined): PatchRecordResult;
+/**
+ * A module's chain: every patch in order, stopping at the first that does
+ * not apply. `applied` is how many did, so the chain the content is AT is
+ * the first `applied` ids -- what its version names.
+ */
+export declare function applyChain(module: ModuleContent, records: readonly PatchRecord[], schema: SerializedSchema | undefined): {
+    module: ModuleContent;
+    applied: number;
+    failed: {
+        patchId: PatchId;
+        message: string;
+    } | null;
+};
+/**
+ * What an entry is in this module: what the chain made it, or -- for one the
+ * chain never touched -- the base's, if the source has its marker.
+ */
+export declare function entryState(module: ModuleContent, key: string): EntryState | undefined;
+/** An entry's content, read. */
+export type EntryContent = {
+    kind: "content";
+    content: ReadonlyJSONValue;
+} | {
+    kind: "missing";
+} | {
+    kind: "error";
+    message: string;
+    patchId?: PatchId;
+};
+/**
+ * An entry's content: what {@link entryState} says, with what it was waiting
+ * for applied. `baseContentOf` is the BASE content of an entry by key (its
+ * `*.val.json`, or what a save left there), `undefined` for one the base does
+ * not have.
+ */
+export declare function resolveEntry(key: string, state: EntryState | undefined, baseContentOf: (key: string) => ReadonlyJSONValue | undefined): EntryContent;

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

@@ -0,0 +1,36 @@
+/**
+ * Where a build's `val.modules` registry can be imported from: phase 9 of
+ * `docs/plans/one-content-model.md`, "Reloading the schema while the Studio
+ * runs".
+ *
+ * A build made by `@valbuild/tanstack-build` (every build the platform
+ * serves) emits its `val.modules` as an ES module of its own beside its
+ * client chunks, named after the build: `/_app/val-modules-<build>.js`,
+ * whose default export is the registry. The server running that build knows
+ * its name (`VAL_BUILD`, Val's `publishBuild`) and names the entry on
+ * `GET /manifest` (`registry`), so a Studio opened on an older build imports
+ * the new one's code and reloads it in place (`HostStore.reloadCode`)
+ * instead of being told to reload the page.
+ *
+ * The convention is the builder's and this file's together: the builder
+ * writes the file (`valModulesEntryFile` in `@valbuild/tanstack-build`, which
+ * does not depend on this package), and each side pins the same literal,
+ * `val-modules-<build>.js` (`buildRegistry.test.ts` here, `valModules.test.ts`
+ * there).
+ */
+/** The file a build's registry is emitted as, among its client chunks. */
+export declare function valModulesEntryFile(build: string): string;
+/** Where a build served by the platform serves its registry. */
+export declare function valModulesEntryPath(build: string): string;
+/**
+ * What `GET /manifest` says about the code of the build that answered:
+ * where its registry is, and which Val it runs. A Studio running another
+ * Val cannot take the build's code in (its own stores would run against a
+ * new core), so it reloads itself instead (`other-val-version`).
+ */
+export type BuildRegistry = {
+    /** The registry's entry, from the site's origin. */
+    entry: string;
+    /** `@valbuild/core`'s version, as the build runs it. */
+    core: string;
+};

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

@@ -0,0 +1,110 @@
+import { type SerializedSchema } from "@valbuild/core";
+import { result } from "@valbuild/core/fp";
+import { PatchError, type JSONValue, type Operation } from "@valbuild/core/patch";
+/**
+ * Classification of a single patch op against a module's serialized schema,
+ * used by the commit flow to route ops for `.jsonValues()` records:
+ *
+ * - `normal`: the op does not descend into a `.jsonValues()` entry; apply it to
+ *   the `.val.ts` as usual.
+ * - `entry`: the op targets a `.jsonValues()` entry. `recordPath` is the path to
+ *   the record within the module source (empty for a root record/router),
+ *   `entryKey` is the entry key, and `subPath` is the remaining path inside the
+ *   entry (empty when the op targets the entry value itself, e.g. add/remove of
+ *   the whole entry).
+ */
+export type JsonValuesOpClass = {
+    kind: "normal";
+} | {
+    kind: "entry";
+    recordPath: string[];
+    entryKey: string;
+    subPath: string[];
+};
+/**
+ * Walks the serialized schema following the op path. When a `.jsonValues()`
+ * record is encountered, the next path segment is the entry key and everything
+ * after it lives inside the entry's `*.val.json` (so it does not touch the
+ * `.val.ts`). Returns `{ kind: "normal" }` when the op never enters a
+ * `.jsonValues()` record.
+ */
+export declare function classifyJsonValuesOp(schema: SerializedSchema, opPath: string[]): JsonValuesOpClass;
+/**
+ * Is this op a write of the WHOLE record at the root of a `.jsonValues()`
+ * module?
+ *
+ * The one op {@link classifyJsonValuesOp} cannot classify: it finds the entry
+ * key by walking the op path, and the root path has no segments to walk, so a
+ * root write reads as `normal` and gets applied to the `.val.ts` - writing
+ * markers over the `c.json(() => import(...))` calls that make the entries load
+ * at all. {@link expandJsonValuesRootOp} turns it into ops that DO name a key,
+ * which everything downstream already handles.
+ *
+ * `add` counts as well as `replace`: at the root both mean "the document is now
+ * this" (see `JSONOps`), so both have to be expanded or the unexpanded one is
+ * the same bug again.
+ *
+ * The value has to BE a record, and that is part of the question rather than a
+ * check inside the expansion: a `.jsonValues()` record can be nullable, and
+ * `null` at the root means the module no longer has a record at all - there are
+ * no entries to write, and it is an ordinary `.val.ts` write, exactly as it was
+ * before any of this existed. Same for any other non-record value: not a
+ * whole-record write, so not this conversion's to route.
+ */
+export declare function isJsonValuesRootOp(schema: SerializedSchema, op: Operation): boolean;
+/**
+ * One entry as it stands right now, for {@link expandJsonValuesRootOp} to
+ * expand against.
+ *
+ * The key set decides add-vs-replace-vs-remove. The content, where the caller
+ * has it, decides whether an op is emitted at all: an entry whose content is
+ * already what the root write says is left alone rather than rewritten, so
+ * putting a module back does not touch every `*.val.json` it did not change.
+ * `undefined` means "this entry exists, content unknown" - which is what the
+ * Studio's draft source has, because the source holds markers - and yields a
+ * `replace`, the safe answer.
+ */
+export type CurrentJsonEntries = ReadonlyMap<string, JSONValue | undefined>;
+/**
+ * Fans a whole-record write at a `.jsonValues()` module's root out into ops
+ * that each name an entry key.
+ *
+ * This is THE conversion, and it has exactly one implementation on purpose: the
+ * commit flow (`ValOps.prepare`) and the engine that builds draft content
+ * (`applyPatchRecord`) both expand through here, so a draft
+ * cannot show something other than what publishing writes. A second
+ * implementation of the same rule would differ silently, which is the whole
+ * failure mode this exists to prevent.
+ *
+ * The value must be the entries' CONTENT. A module's Source is markers, not
+ * content, so a Source handed over here is refused rather than written: that is
+ * the shape of the original bug (a revert replaying the archived Source), and
+ * it is not recoverable afterwards - the markers replace the entries' content
+ * on disk.
+ */
+export declare function expandJsonValuesRootOp(op: Operation, currentEntries: CurrentJsonEntries): result.Result<Operation[], PatchError>;
+/**
+ * What a whole-record write says about ONE entry: the same rule
+ * {@link expandJsonValuesRootOp} applies to all of them.
+ *
+ * For a reader that is about one entry. Expanding the whole record to find the
+ * one op that names its key costs an op per entry per entry read - the record
+ * squared, on exactly the large records this feature is for. The rule itself is
+ * `writeForEntry`, shared with the expansion above, so the two cannot come to
+ * disagree; only the loop around it differs.
+ *
+ * `null` means the write says nothing about this entry: it holds that content
+ * already, or the record does not name it and it does not exist.
+ */
+export declare function expandJsonValuesRootOpForKey(op: Operation, entryKey: string, currentEntries: CurrentJsonEntries): result.Result<Operation | null, PatchError>;
+/**
+ * Rebases a patch op that targets a `.jsonValues()` entry's content so its paths
+ * are relative to the entry's `*.val.json` root (drops the record + entry-key
+ * prefix). Used to replay the op against the backing JSON file.
+ */
+export declare function rebaseContentOp(op: Operation, prefixLen: number): result.Result<Operation, PatchError>;
+/**
+ * The entry a path names when it names a WHOLE entry of the root
+ * `.jsonValues()` record, and `undefined` for anything else.
+ */
+export declare function wholeEntryKey(serializedSchema: SerializedSchema | undefined, path: string[]): string | undefined;

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>;