@valbuild/shared 0.148.7 → 0.149.7

package/dist/declarations/src/publish/jobClient.d.ts

@@ -0,0 +1,96 @@
+import { type BuildTargetResponse, type JobStepBody, type PressResponse, type PublishRequestStatus, type PublishTabJob } from "../internal/index.js";
+import { z } from "zod";
+/**
+ * Publishing as a queued job, as a Studio tab speaks it.
+ *
+ * valbuild/home's docs/app-mode.md, "Publishing is a queued job", is the
+ * design: a press is a REQUEST that returns at once; the tab that pressed runs
+ * the job it is given -- prepare, build, upload -- and content runs verify and
+ * the seal. Everything goes through this deployment: the job routes through
+ * the publish proxy, and the prepare through this server's own route, which is
+ * the one place a job's sources can be computed.
+ */
+export type StudioJobClient = {
+    /** A press of Publish. Idempotent on `requestId`. */
+    press(requestId: string, tab: string): Promise<PressResponse>;
+    /**
+     * Publish in a proposal: press the merge of `proposal`. Idempotent on
+     * `requestId`, as `press` is; the merge checks run first and may refuse it.
+     * From the press on it is a request like any other.
+     */
+    pressMerge(proposal: string, requestId: string, tab: string, 
+    /**
+     * The checks the person chose to publish over, having been told what
+     * failed: `types`, an upgrade's new type errors (Publish anyway on home's
+     * upgrade page). Content refuses it over anything else.
+     */
+    anyway?: "types"[]): Promise<PressResponse>;
+    /** Try again: resume a paused queue and press anew. */
+    tryAgain(requestId: string, tab: string): Promise<PressResponse>;
+    /** Where a press is. */
+    requestStatus(requestId: string): Promise<PublishRequestStatus>;
+    /** A free tab asking for queued work. */
+    next(tab: string): Promise<PublishTabJob | null>;
+    /** The job's prepare, by this server: its sources, and content's archive of them. */
+    prepare(job: PublishTabJob, tab: string): Promise<PreparedJob>;
+    /** The tab reports a step it ran. */
+    step(jobId: string, body: JobStepBody): Promise<PublishTabJob | null>;
+    /** The tab is still building. `false`: it no longer holds the job. */
+    renew(jobId: string, tab: string): Promise<boolean>;
+    cancel(jobId: string): Promise<boolean>;
+    /** Discard a failed job's changes; answers what another job still holds. */
+    discard(jobId: string): Promise<string[]>;
+    /**
+     * Connected: the newest CI run the branch's workflow reported -- where
+     * "View run" goes for a build that failed. `null` when none was reported.
+     */
+    newestCiRun(): Promise<{
+        status: "failed" | "succeeded";
+        url: string | null;
+    } | null>;
+};
+/** What the tab builds a job from: `/api/val/publish-job-prepare`'s answer. */
+export type PreparedJob = {
+    job: PublishTabJob | null;
+    sourceFiles: Record<string, string | null>;
+    binaryFiles: Record<string, string>;
+    binaryFilesUnread: string[];
+    branch: string | null;
+    /** Can this tab build the job from these sources? See the route's `buildable`. */
+    buildable: boolean;
+    /**
+     * What to build against, when it is not the site's: a merge of a proposal
+     * that changed its dependencies builds on the proposal's own framework and
+     * layer (valbuild/home `docs/adept.md`, step 6). Absent, the deploy asks
+     * the site's, as it always did.
+     */
+    target?: BuildTargetResponse;
+};
+export declare function createStudioJobClient(options: ({
+    api: string;
+} | {
+    /** Content's publish API itself: see `PublishApiAt`. */
+    publishApi: string;
+    /** The project's proposals on content, `<content>/v1/<org>/<project>/proposals`. */
+    proposalsApi: string;
+}) & {
+    fetchImpl?: typeof fetch;
+}): StudioJobClient;
+/** A job's change that merges a proposal: `merge:<name>` (content's `mergeChange`). */
+export declare function isMergeChange(change: string): boolean;
+/** `/publish-jobs/:id/merge-prepare`'s answer: the merge's files, from content. */
+export declare const MergePrepareAnswer: z.ZodObject<{
+    job: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        step: z.ZodNullable<z.ZodEnum<{
+            prepare: "prepare";
+            build: "build";
+            upload: "upload";
+        }>>;
+        base: z.ZodNullable<z.ZodString>;
+        patches: z.ZodArray<z.ZodString>;
+        contentOnly: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>>;
+    sourceFiles: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
+    target: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;

package/dist/declarations/src/publish/loadedLayer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Has the site moved onto other dependencies since this page loaded?
+ *
+ * A managed project's Studio is served by the site's own live build, so the
+ * Studio on screen -- its builder, its Val -- is the version that build was
+ * made with. When the site is updated (Settings → Updates, in this tab or
+ * another), every Studio opened before that is the OLD version, and a publish
+ * from one would build the site with the old builder, or, if it read its build
+ * target before the update went live, put the old dependencies back.
+ *
+ * So the page remembers which dependency layer the live build had when it
+ * loaded, and a publish compares that with the live build's now. They differ
+ * only when somebody moved the site's dependencies in between; the answer is
+ * to reload, which loses nothing -- unpublished changes are the server's.
+ *
+ * Read from `/__api/head`, which the platform answers on every site without a
+ * credential and which names the layer (`projectVendorRev`). Anything that
+ * cannot answer -- not on the platform, the loader unreachable, an older
+ * loader -- reads as "cannot tell", and "cannot tell" never blocks a publish.
+ */
+/**
+ * The layer, or `undefined` for "cannot tell". `null` is never READ -- a head
+ * that names no layer is "cannot tell" too, see `readLiveLayer` -- but is what
+ * a build target says for a project with none, which is why it is comparable.
+ */
+export type LayerReading = string | null | undefined;
+export declare function readLiveLayer(fetchImpl?: typeof fetch): Promise<LayerReading>;
+/**
+ * Stale only on a positive answer from both readings. A page that could not
+ * tell what it loaded on, or cannot tell now, publishes as before.
+ */
+export declare function layerMoved(loaded: LayerReading, now: LayerReading): boolean;
+/**
+ * Take the reading this page is compared against. Once per page: the first
+ * call wins, because a later one would record the layer an update just moved
+ * to and make a stale page look current.
+ */
+export declare function rememberLoadedLayer(fetchImpl?: typeof fetch): void;
+/** What {@link rememberLoadedLayer} read, or `undefined` if it never ran. */
+export declare function loadedLayer(): Promise<LayerReading>;
+/** Has the live build's layer moved since this page loaded? */
+export declare function siteMovedSinceLoad(fetchImpl?: typeof fetch): Promise<boolean>;
+/** The code a deploy refuses with when this page is out of date. */
+export declare const STUDIO_OUT_OF_DATE = "STUDIO_OUT_OF_DATE";
+export declare const STUDIO_OUT_OF_DATE_MESSAGE: string;
+export declare function markStudioOutOfDate(): void;
+export declare function studioOutOfDateRefusals(): number;
+export declare function subscribeStudioOutOfDate(listener: () => void): () => void;
+/** For tests: forget everything this module has learnt. */
+export declare function resetLoadedLayerForTests(): void;

package/dist/declarations/src/publish/proposalProject.d.ts

@@ -0,0 +1,2 @@
+/** The proposal's project: the site's source, with what the proposal changed laid over it. */
+export declare function proposalProject(site: Record<string, string>, own: Record<string, string | null>): Record<string, string>;

package/dist/declarations/src/publish/publishClient.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The Studio's side of the content service's publish API.
+ *
+ * Same conversation `val publish` has -- declare, upload, confirm, verify,
+ * promote -- and deliberately the same PARSERS: `parseDeclare` and the rest
+ * come from `@valbuild/shared/internal`, where they live precisely so that two
+ * publishers cannot come to disagree about what content said.
+ *
+ * ## Two things differ from the CLI's client, and both are the same fact
+ *
+ * A browser holds a session cookie for the app's origin and no credential
+ * content would accept -- content's publish API takes a project token and
+ * refuses everything else. So:
+ *
+ * - **Every call goes to this origin**, at `/api/val/publish-api`, and the
+ *   deployment swaps the credential on the way (see `ValOpsHttp.publishApi`).
+ *   Nothing here has a token, and nothing here should ever be given one.
+ * - **The uploads do not.** A slot is a presigned URL for object storage, and
+ *   those bytes go straight there rather than through the isolate -- which is
+ *   the whole reason the API hands out slots instead of accepting the artifacts
+ *   itself. `credentials: "omit"` on those, because a presigned URL carries its
+ *   own authorisation and a cookie sent to a storage host is a cookie leaked to
+ *   one.
+ */
+import { ArtifactsResponse, BuildTargetResponse, DeclareBody, DeclareResponse, PromoteResponse, StatusResponse, UploadSlot, VerifyResponse } from "../internal/index.js";
+export { StudioPublishError, callJson, isTransientPublishError, } from "./callJson.js";
+/** An artifact the live build has and this publish re-declares by hash. */
+export type CarriedArtifact = {
+    key: string;
+    sha256: string;
+    bytes: number;
+};
+/** See {@link StudioPublishClient.publicFiles}. */
+export type LivePublicFiles = {
+    carried: CarriedArtifact[];
+} | {
+    paths: string[];
+} | null;
+/** Object storage refused the bytes, or could not be reached. */
+export declare class StudioUploadError extends Error {
+    readonly statusCode: number;
+    readonly key: string;
+    constructor(statusCode: number, key: string, message: string);
+}
+export type StudioPublishClient = {
+    /**
+     * What to build against, and what to build -- the two reads a publish makes
+     * before it has anything to declare.
+     *
+     * On this type rather than beside it because they go through the same proxy
+     * with the same credential, and because a caller holding one of them and not
+     * the other can do nothing at all.
+     */
+    buildTarget(): Promise<BuildTargetResponse>;
+    /** `null` when the project has never published. */
+    projectSource(): Promise<Record<string, string> | null>;
+    /**
+     * What the live build serves from `public/`: by hash when content published
+     * it, by path when only the loader knows, `null` when neither can say. See
+     * `publicFiles` and `publicPaths` on `GET /v1/project-source`, which this
+     * reads with {@link projectSource} in one request.
+     */
+    publicFiles(): Promise<LivePublicFiles>;
+    declare(body: DeclareBody): Promise<DeclareResponse>;
+    confirmArtifacts(publishId: string): Promise<ArtifactsResponse>;
+    verify(publishId: string): Promise<VerifyResponse>;
+    promote(publishId: string): Promise<PromoteResponse>;
+    status(publishId: string): Promise<StatusResponse>;
+    /** The artifact's bytes, straight to object storage. */
+    upload(slot: UploadSlot, body: string): Promise<void>;
+};
+/**
+ * A slot's permission to write has run out.
+ *
+ * Its own shape because it is not a failure: the answer is to declare again for
+ * fresh slots, and a publish that treated it as one would give up an upload
+ * short of the finish.
+ */
+export declare function isExpiredSlot(error: unknown): boolean;
+/**
+ * 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;
+export declare function createStudioPublishClient(options: PublishApiAt & {
+    fetchImpl?: typeof fetch;
+}): StudioPublishClient;

package/dist/declarations/src/publish/runStudioDeploy.d.ts

@@ -0,0 +1,244 @@
+/**
+ * A build, from the Studio, handed to content.
+ *
+ * Two callers. A publish JOB's tab builds the job's content and stops once
+ * its artifacts are confirmed (`until: "confirmed"`): content verifies and
+ * seals it, and mints the commit then (valbuild/home, docs/app-mode.md,
+ * "Publishing is a queued job"). An UPDATE builds the live content against a
+ * new dependency layer and takes it live itself. Either way what is here is
+ * the part a managed project has nobody else to do -- read what to build and
+ * what to build it from, build it, and hand the result to content.
+ *
+ * ## Everything it cannot do itself is a parameter
+ *
+ * There are four, and each is something this package must not contain:
+ *
+ * - **`client`** reaches content through this origin's proxy. A browser holds
+ *   a session cookie and no project token; the deployment swaps the credential.
+ * - **`loadBuilder`** is the dynamic import, replaceable because nothing that
+ *   imports it for real runs under jest — `@rolldown/browser` is ESM-only and
+ *   this repository's jest is CommonJS.
+ * - **`generateRouteTree`** is TanStack's generator plus babel, which is 2.6 MB
+ *   and is not on npm. See {@link StudioDeployOptions.generateRouteTree}.
+ * - **`commit`** is the commit an update is wired at, which only the caller has.
+ *
+ * So this module is testable without any of them, which is the point: the
+ * sequence is where the mistakes are, and the sequence is what is left.
+ *
+ * ## It does not throw
+ *
+ * Same rule as `runStudioPublish`, and for the same reason: every failure here
+ * means one thing to an editor — nothing is live, and here is why — so a caller
+ * that had to distinguish eight rejections would write eight identical
+ * branches. The `problems` from content survive because they are the only part
+ * a person can act on.
+ */
+import type { BuildTarget } from "@valbuild/tanstack-build";
+import { PublishProblem } from "../internal/index.js";
+import { CarriedArtifact, StudioPublishClient } from "./publishClient.js";
+import { PublishPhase } from "./runStudioPublish.js";
+import type { StudioBuilder } from "./builder.js";
+import { LayerReading } from "./loadedLayer.js";
+/**
+ * The binary files a commit wrote, as `/save` answered them.
+ *
+ * `unread` is files the server could not read back before committing. The
+ * build refuses over them: the site would link a file it does not serve.
+ */
+export type CommittedBinaryFiles = {
+    files: Record<string, string>;
+    unread: string[];
+};
+export type DeployPhase = 
+/**
+ * A publish job waiting its turn: queued behind the one before it. Never
+ * reported by the deploy itself -- it is how the Studio shows a press whose
+ * job has not started (see `publishProgress`).
+ */
+{
+    kind: "queued";
+}
+/** Waiting for the bundler. Only ever seen when the preload has not landed. */
+ | {
+    kind: "getting-ready";
+} | {
+    kind: "reading";
+} | {
+    kind: "building";
+} | PublishPhase;
+export type StudioDeployResult = {
+    status: "live";
+    url: string | null;
+} | {
+    status: "already-live";
+    url: string | null;
+}
+/** A publish job's build, uploaded and confirmed: content does the rest. */
+ | {
+    status: "uploaded";
+    publishId: string;
+} | {
+    status: "failed";
+    message: string;
+    problems: PublishProblem[];
+};
+export interface StudioDeployOptions {
+    client: StudioPublishClient;
+    /**
+     * For a publish job's tab: stop once the artifacts are confirmed, and
+     * answer with the publish id. Content runs verify and the seal itself, and
+     * `commit` is `null` -- a job's build is wired at no commit, because its
+     * commit is minted at the seal (valbuild/home, docs/app-mode.md: "A
+     * platform build bakes nothing and asks content").
+     */
+    until?: "confirmed";
+    /**
+     * The commit `/save` just made, or `null` for a publish from no commit.
+     *
+     * The BRANCH is deliberately not here, because the caller has no honest
+     * source for one: `/stat` does not carry it and neither does `/save`, and a
+     * branch the browser invented is a branch content would be asked to record a
+     * build against on the browser's say-so. It is read out of the project's own
+     * `val.server.ts` instead — see {@link branchOf} — which is where the last
+     * build put it and which does not change between publishes.
+     *
+     * The commit is baked in before the build, and that is not bookkeeping: Val
+     * reads content from the content service AT A COMMIT, so a build wired at
+     * the previous one renders and edits a different version of its files than
+     * the code it is running.
+     */
+    commit: string | null;
+    /**
+     * The publish job this build is for, baked in beside the commit so the
+     * build can say where it sits in the content service's chain -- it has no
+     * commit to say it with (`BUILT_FOR_JOB` in `@valbuild/tanstack-build`).
+     * Left out by a build that is not a job's (an update), which keeps the job
+     * of the source it was made from: an update changes no content.
+     */
+    job?: string | null;
+    /**
+     * The source files to build, by path, over the project's stored source --
+     * for a publish job, every file of the job's content, as the server's
+     * `/publish-job-prepare` rendered it -- or `null` when there are none to add
+     * (an update, which changes no content).
+     *
+     * Laid over the stored source before anything else, because the stored
+     * source is what the LAST build was made from: without this the build
+     * publishes the site as it was before the change. `null` values are files
+     * the change deleted. Paths may carry a leading `/` (Val's module paths do)
+     * and are matched without it.
+     */
+    committedFiles?: Record<string, string | null> | null;
+    /**
+     * The binary files that commit wrote -- an image uploaded in this save --
+     * base64 by path, or `null` when there are none to add.
+     *
+     * Nothing else has them: the stored source is text, and the live build
+     * predates the upload. A file under `public/` is published as one; anything
+     * else goes to the build as an asset, where an import can find it.
+     */
+    committedBinaryFiles?: CommittedBinaryFiles | null;
+    /**
+     * The branch the commit is on, as the server had it from the content
+     * service, or `null` when it did not say.
+     *
+     * Preferred over the branch baked into the last build's `val.server.ts`,
+     * which is the fallback: a project cloned from a template seed was wired at
+     * no commit and no branch, and a branchless publish is refused by a loader
+     * whose pointer follows one -- which admin configures for every project.
+     */
+    branch?: string | null;
+    /**
+     * The live site's compiled stylesheet, used when this build produced none.
+     *
+     * A build in the browser cannot run Tailwind `@plugin`s, and the stored
+     * source may not carry the stylesheets at all. A Studio save changes content
+     * and uploaded files, never a stylesheet or a component, so the live CSS is
+     * still the right CSS; without this every Studio publish shipped unstyled.
+     */
+    liveStylesheet?: () => Promise<string>;
+    /**
+     * One of the live site's public files, base64, by its URL path
+     * (`favicon.ico` for `/favicon.ico`).
+     *
+     * Only asked for when content cannot name the live build's public files by
+     * hash and the loader can name them by path. Absent, that case is refused
+     * like the one where nobody can say.
+     */
+    fetchPublicFile?: (path: string) => Promise<string>;
+    /**
+     * What to build against, when it is not what the live build was built
+     * against.
+     *
+     * Absent for every publish but one: an update, which moves the project onto
+     * its template's current dependency layer. The live build's target names the
+     * layer it is leaving, so the update's own answer is used instead -- and the
+     * publish then names the layer it carries, which is what moves the site.
+     */
+    target?: BuildTarget;
+    /**
+     * The dependency layer the live build had when this page loaded (see
+     * `loadedLayer.ts`), or `undefined` when it cannot say.
+     *
+     * A publish whose build target names a different one is refused: the site
+     * was updated since, this Studio is the old version, and building with it
+     * would use the old builder. Not asked of an update, whose whole point is a
+     * different layer.
+     */
+    loadedLayer?: LayerReading;
+    /**
+     * The live build's layer NOW. Asked once more after the build, just before
+     * the declare: an update that went live while this page was building would
+     * pass the check against the target read at the start, and this publish
+     * would then put the old dependencies back. Absent, only that first check
+     * is made. What closes the remaining window -- declare to promote -- is the
+     * seal in publish-jobs.
+     */
+    liveLayer?: () => Promise<LayerReading>;
+    loadBuilder: () => Promise<StudioBuilder>;
+    /**
+     * Generates `src/routeTree.gen.ts` for a file-based project.
+     *
+     * A capability, like `routeSplitter` and `loadCssModule` on `BuildInput` and
+     * for the same reason: it is TanStack's generator over babel, it is 2.6 MB
+     * built for a browser, and it is not published. A deployment that has one
+     * supplies it.
+     *
+     * Absent, a file-based project is REFUSED by name. It would otherwise fail
+     * inside rolldown with `UNRESOLVED_ENTRY`, because a file-based project's
+     * entry IS the generated tree — a message about a module specifier, for a
+     * missing capability, several layers from anything anyone can act on.
+     */
+    generateRouteTree?: (files: Record<string, string>) => Promise<Record<string, string>>;
+    onPhase: (phase: DeployPhase) => void;
+}
+export declare function runStudioDeploy(options: StudioDeployOptions): Promise<StudioDeployResult>;
+/**
+ * The stored source with a commit's files laid over it.
+ *
+ * A new record rather than an edit of the one read, which the caller may still
+ * hold. Val names module files with a leading `/`; the stored record does
+ * not, so the slash is dropped -- two spellings of one path would build the
+ * old file and publish the new one beside it.
+ */
+export declare function withCommittedFiles(source: Record<string, string>, committed: Record<string, string | null> | null): Record<string, string>;
+/**
+ * A commit's binary files, as the build takes them: `public/...` served as is,
+ * everything else an asset an import can reach. Keys lose the leading `/`
+ * Val's paths carry, as in {@link withCommittedFiles}.
+ */
+export declare function splitBinaryFiles(files: Record<string, string>): {
+    publicFiles: Record<string, string>;
+    assets: Record<string, string>;
+};
+/**
+ * The live build's public files this build keeps, re-declared by hash.
+ *
+ * All of them, except the ones this build produced itself (a file the commit
+ * replaced) and the ones the commit deleted. Content holds the bytes already,
+ * so this uploads nothing -- and if it has lost one, it asks for it, and
+ * `runStudioPublish` refuses rather than publishing a hole.
+ */
+export declare function carriedInto(built: ReadonlyArray<{
+    key: string;
+}>, carried: ReadonlyArray<CarriedArtifact>, committed: Record<string, string | null> | null): CarriedArtifact[];

package/dist/declarations/src/publish/runStudioJob.d.ts

@@ -0,0 +1,102 @@
+import type { PublishTabJob } from "../internal/index.js";
+import type { DeployPhase, StudioDeployResult } from "./runStudioDeploy.js";
+import type { PreparedJob, StudioJobClient } from "./jobClient.js";
+/**
+ * A publish job, as the tab that holds it runs it: prepare, build, upload --
+ * and then it is content's (valbuild/home, docs/app-mode.md, "Publishing is a
+ * queued job"). Content runs verify and the seal, and "Live" arrives on the
+ * websocket, so a tab that closes after its upload costs nothing.
+ *
+ * The tab holds the job by a lease, renewed on a timer while it works. A
+ * renewal answered `false` means the job is no longer this tab's -- its lease
+ * lapsed and its requests went back to the queue, or it was cancelled -- and
+ * the tab stops: another tab, or this one's next job, will build it.
+ *
+ * Every step is reported by name, so a report retried after a lost answer
+ * does nothing twice, and a failure is reported as the step's: content counts
+ * the attempts and, after the last, fails the job with Try again.
+ */
+export type JobPhase = {
+    kind: "preparing";
+} | {
+    kind: "deploying";
+    phase: DeployPhase;
+} | {
+    kind: "handing-off";
+};
+export type StudioJobResult = 
+/**
+ * The tab's part is done, and content has the job. `built`: this tab built
+ * and uploaded it. `false` is a job whose build is CI's -- a connected
+ * project's, where the tab's part is the prepare alone -- or, with
+ * `contentOnly`, a job nobody builds: its content goes live on the build
+ * already live.
+ */
+{
+    status: "handed-off";
+    jobId: string;
+    built: boolean;
+    contentOnly?: true;
+}
+/** The job is no longer this tab's. Nothing to report. */
+ | {
+    status: "lost";
+    jobId: string;
+}
+/**
+ * A managed job that needs a build, prepared by a tab that cannot run the
+ * builder (`buildsElsewhere`). Not reported: its lease lapses, it goes back
+ * to the queue, and a builder tab -- opened with one more tap -- takes it.
+ */
+ | {
+    status: "needs-builder";
+    jobId: string;
+}
+/** A step failed, and was reported as failed. */
+ | {
+    status: "failed";
+    jobId: string;
+    message: string;
+};
+/** How often the tab renews its lease. Content's job lease is 30 s. */
+export declare const RENEW_EVERY_MS = 10000;
+export declare function runStudioJob(options: {
+    client: StudioJobClient;
+    job: PublishTabJob;
+    tab: string;
+    /**
+     * Build the job from its prepared sources, stopping once the artifacts are
+     * confirmed: `runStudioDeploy` with `until: "confirmed"` and no commit.
+     */
+    deploy: (prepared: PreparedJob, onPhase: (phase: DeployPhase) => void) => Promise<StudioDeployResult>;
+    onPhase: (phase: JobPhase) => void;
+    renewEveryMs?: number;
+    /**
+     * Can this tab build at all? Connected only: a tab that cannot (no
+     * cross-origin isolation) reports "no build", and CI builds the push. A
+     * managed job never reaches a tab that cannot -- it is handed to one that can.
+     */
+    canBuild?: () => boolean;
+    /**
+     * Managed, and a tab that cannot build: an iPhone, or the overlay, running
+     * its own publish so that one of content alone needs no tab. A job that
+     * needs a build after all is given back (`needs-builder`) rather than said
+     * to need none -- content refuses that for a managed job, which has no CI.
+     */
+    buildsElsewhere?: boolean;
+}): Promise<StudioJobResult>;
+/**
+ * Run a job until this tab's part of it is over: handed off, lost, or failed
+ * for good.
+ *
+ * A failed step is counted by content, which keeps the job at that step for
+ * the tab to run again -- until its last attempt, when it fails the job.
+ * Whether it is still this tab's is the renewal's answer, so a failure is
+ * followed by one, and a `true` runs it again.
+ */
+export declare function runJobToEnd(options: {
+    client: Pick<StudioJobClient, "renew">;
+    job: PublishTabJob;
+    tab: string;
+    run: () => Promise<StudioJobResult>;
+}): Promise<StudioJobResult>;

package/dist/declarations/src/publish/runStudioPublish.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Publishing what the tab just built.
+ *
+ * The same conversation `val publish` has, with the same parsers, and the same
+ * shape of state machine -- declare, upload what content does not already hold,
+ * confirm, verify, promote. It is written out again here rather than shared
+ * with the CLI's `runPublish` because the two differ in every input and in what
+ * they do when something goes wrong: the CLI reads artifacts off a disk it
+ * controls, takes a token, prints lines and sets an exit code; this holds them
+ * in memory, has no credential, and has to leave an EDITOR with something they
+ * can act on.
+ *
+ * What is shared is what must not drift: the wire shapes and their parsers
+ * (`@valbuild/shared/internal`) and the artifact key namespace
+ * (`@valbuild/tanstack-build`). Those are the parts where a second, slightly
+ * different copy is how two publishers come to disagree with one service.
+ *
+ * ## No progress reporting beyond phases, on purpose
+ *
+ * Byte-level upload progress would need `XMLHttpRequest` per artifact, and a
+ * publish is dozens of small ones rather than one big one -- so what a person
+ * sees from counting artifacts is the same and the code is a quarter the size.
+ *
+ * ## Why it never throws
+ *
+ * Every exit is a value. A publish that failed has to say WHICH step and leave
+ * the commit intact; a thrown error at an await boundary in a React handler is
+ * an unhandled rejection and a spinner that never stops.
+ */
+import type { PublishArtifact } from "@valbuild/tanstack-build";
+import { type DeclareBody, type PublishProblem } from "../internal/index.js";
+import { StudioPublishClient } from "./publishClient.js";
+/** Which step the publish is on, for the one line an editor is shown. */
+export type PublishPhase = {
+    kind: "declaring";
+} | {
+    kind: "uploading";
+    done: number;
+    total: number;
+} | {
+    kind: "confirming";
+} | {
+    kind: "verifying";
+} | {
+    kind: "promoting";
+};
+export type StudioPublishResult = {
+    status: "live";
+    publishId: string;
+    url: string | null;
+}
+/** Content had already taken this exact build. Not a failure. */
+ | {
+    status: "already-live";
+    publishId: string;
+    url: string | null;
+}
+/**
+ * Stopped after the artifacts were confirmed, as `until: "confirmed"` asks:
+ * a publish JOB's tab does no more than that, and content runs verify and
+ * the seal (valbuild/home, docs/app-mode.md, "Publishing is a queued job").
+ */
+ | {
+    status: "uploaded";
+    publishId: string;
+} | {
+    status: "failed";
+    /** `null` when it failed before content had accepted anything. */
+    publishId: string | null;
+    message: string;
+    problems: PublishProblem[];
+};
+export declare function runStudioPublish(args: {
+    client: StudioPublishClient;
+    artifacts: PublishArtifact[];
+    declare: DeclareBody;
+    onPhase: (phase: PublishPhase) => void;
+    /** Stop once the artifacts are confirmed: for a publish job's tab. */
+    until?: "confirmed";
+}): Promise<StudioPublishResult>;