gutterpress 0.11.23-alpha.6 → 0.11.23-beta.1

package/dist/index.js

@@ -21,6 +21,7 @@ import {
   SYNC_SNAPSHOT_MESSAGE,
   VERSION_CHANGES_SHOWN,
   adoptFolder,
+  assembleCssChunks,
   autoSnapshotDelayMs,
   autoSyncDelayMs,
   checkCss,
@@ -70,6 +71,7 @@ import {
   listPublishProviders,
   listRepoBooks,
   listSnippets,
+  listVersionChanges,
   openPath,
   parseRemoteOrigin,
   pkceChallengeFromVerifier,
@@ -80,6 +82,7 @@ import {
   readPageSetup,
   readPublishSettings,
   refreshRemoteCopies,
+  relDisplay,
   renameRevision,
   repairOnlineBackup,
   reportMissingTools,
@@ -119,7 +122,7 @@ import {
   substituteVariables,
   syncProject,
   testRemoteAccess
-} from "./index-ejbfetdn.js";
+} from "./index-c6y0p7jy.js";
 import {
   DEFAULT_NPM_REGISTRY,
   MANIFEST_FILENAMES,
@@ -149,7 +152,7 @@ import {
   setExtensionEnabled,
   updateExtensions,
   validateProjectExtensions
-} from "./index-cmakyf43.js";
+} from "./index-rj5vrhz6.js";
 import {
   BUNDLED_EXTENSIONS,
   EXTENSION_MANIFEST_FILENAME,
@@ -160,20 +163,21 @@ import {
   extensionStyleList,
   isBundledExtension,
   isPathSpecifier,
+  loadPluginsWithCss,
   log,
   parseExtensionSpecifier,
   pathEscapesFolder,
   readExtensionMeta,
   resolveExtension
-} from "./index-1zqkfzcd.js";
+} from "./index-a4j3xcfp.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-wm4x7xbf.js";
-import"./index-2vxzxyyj.js";
+} from "./index-fk2kpf2t.js";
+import"./index-798jt0qc.js";
 import {
   BuildError
-} from "./index-46ycxe6r.js";
+} from "./index-tayzfr9c.js";
 import"./index-5crpmz42.js";
 import {
   DEFAULT_PRINT_OPTS,
@@ -207,6 +211,226 @@ import {
   repoSubPath
 } from "./index-v5mp7a6q.js";
 import"./index-37x76zdn.js";
+// src/lib/book-css.ts
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+// src/lib/root-tokens.ts
+import postcss from "postcss";
+var DIRECTIVE_RE = /@(group|label|internal)\b[ \t]*([^\n\r@]*)/gi;
+function fold(into, comment) {
+  for (const d of comment.matchAll(DIRECTIVE_RE)) {
+    const key = d[1].toLowerCase();
+    if (key === "internal") {
+      into.internal = true;
+      continue;
+    }
+    const value = d[2].trim();
+    if (value)
+      into[key] = value;
+  }
+}
+function rootRules(root) {
+  const out = [];
+  const visit = (container, layer) => {
+    container.each((node) => {
+      if (node.type === "rule") {
+        if (node.selectors.some((s) => s.trim().toLowerCase() === ":root")) {
+          out.push(layer === undefined ? { rule: node } : { rule: node, layer });
+        }
+      } else if (node.type === "atrule" && node.name.toLowerCase() === "layer" && node.nodes) {
+        const name = node.params.trim();
+        visit(node, layer === undefined ? name : name ? `${layer}.${name}` : layer);
+      }
+    });
+  };
+  visit(root, undefined);
+  return out;
+}
+function leadingComments(rule) {
+  const out = [];
+  for (let prev = rule.prev();prev?.type === "comment"; prev = prev.prev())
+    out.unshift(prev.text);
+  return out;
+}
+function writtenValue(decl) {
+  return decl.raws.value?.raw ?? decl.value;
+}
+function rootTokens(css) {
+  const out = [];
+  for (const { rule, layer } of rootRules(postcss.parse(css))) {
+    const defaults = {};
+    for (const comment of leadingComments(rule))
+      fold(defaults, comment);
+    let pending = {};
+    rule.each((node) => {
+      if (node.type === "comment") {
+        fold(pending, node.text);
+        return;
+      }
+      if (node.type !== "decl" || !node.prop.startsWith("--"))
+        return;
+      const own = pending;
+      pending = {};
+      const annotated = own.group !== undefined || own.label !== undefined;
+      if (own.internal || defaults.internal && !annotated)
+        return;
+      const group = own.group ?? defaults.group;
+      out.push({
+        name: node.prop,
+        value: writtenValue(node),
+        ...own.label !== undefined ? { label: own.label } : {},
+        ...group !== undefined ? { group } : {},
+        ...layer !== undefined ? { layer } : {}
+      });
+    });
+  }
+  return out;
+}
+function declarationsOf(root, name) {
+  return rootRules(root).flatMap(({ rule }) => (rule.nodes ?? []).filter((n) => n.type === "decl" && n.prop === name));
+}
+function removeDeclaration(decl) {
+  const rule = decl.parent;
+  decl.remove();
+  if ((rule.nodes ?? []).length > 0)
+    return;
+  const parent = rule.parent;
+  const next = rule.next();
+  const before = rule.raws.before ?? "";
+  rule.remove();
+  const keep = (after) => before + (after ?? "").replace(/^\n/, "");
+  if (next)
+    next.raws.before = keep(next.raws.before);
+  else
+    parent.raws.after = keep(parent.raws.after);
+}
+function insertDeclaration(root, name, value) {
+  const rule = rootRules(root)[0]?.rule;
+  if (rule) {
+    const hadDeclaration = (rule.nodes ?? []).some((n) => n.type === "decl");
+    rule.prepend(postcss.decl({ prop: name, value, raws: { before: rule.first?.raws.before ?? `
+  `, between: ": " } }));
+    if (!hadDeclaration)
+      rule.raws.semicolon = true;
+    return;
+  }
+  const tail = root.raws.after ?? "";
+  const added = postcss.rule({ selector: ":root", raws: { between: " ", after: `
+`, semicolon: true } });
+  added.append(postcss.decl({ prop: name, value, raws: { before: `
+  `, between: ": " } }));
+  root.append(added);
+  added.raws.before = tail + ((root.nodes.length > 1 || tail) && !tail.endsWith(`
+`) ? `
+` : "");
+  root.raws.after = `
+`;
+}
+function applyTokenUpdates(sheets, target, updates) {
+  const roots = sheets.map((css) => postcss.parse(css));
+  const changed = new Set;
+  for (const { name, value } of updates) {
+    const declared = roots.map((root) => declarationsOf(root, name));
+    if (value === null) {
+      declared.forEach((decls, i) => {
+        for (const decl of decls)
+          removeDeclaration(decl);
+        if (decls.length > 0)
+          changed.add(i);
+      });
+      continue;
+    }
+    let at = declared.length - 1;
+    while (at >= 0 && declared[at].length === 0)
+      at--;
+    if (at >= 0) {
+      for (const decl of declared[at])
+        decl.value = value;
+      changed.add(at);
+    } else {
+      insertDeclaration(roots[target], name, value);
+      changed.add(target);
+    }
+  }
+  return sheets.map((css, i) => changed.has(i) ? roots[i].toString() : css);
+}
+
+// src/lib/book-css.ts
+async function readText(file) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return "";
+    throw error;
+  }
+}
+async function bookSheets(projectDir, styles) {
+  return (await resolveActiveStyles(projectDir, styles)).map((rel) => path.resolve(projectDir, rel));
+}
+async function readBookCss(projectDir) {
+  const { manifest } = await loadManifestWithPath(projectDir);
+  const config = resolveConfig({}, manifest);
+  const { pluginStyles } = await loadPluginsWithCss(config.extensions, projectDir, () => {});
+  const extensions = [];
+  for (const group of pluginStyles) {
+    const layered = (css, file) => {
+      if (!css.trim())
+        return;
+      extensions.push({
+        origin: { kind: "extension", name: group.name, layer: group.layer, ...file ? { file } : {} },
+        css: `@layer ${group.layer} {
+${css.trim()}
+}`
+      });
+    };
+    for (const file of group.paths)
+      layered(await readText(file), relDisplay(projectDir, file));
+    if (group.css)
+      layered(group.css);
+  }
+  const book = [];
+  for (const file of await bookSheets(projectDir, config.styles)) {
+    const css = await readText(file);
+    if (css.trim())
+      book.push({ origin: { kind: "book", file: relDisplay(projectDir, file) }, css });
+  }
+  const chunks = assembleCssChunks({
+    printArea: { ...config.page, preset: config.preset, spec: config.spec },
+    extensions,
+    book
+  });
+  return {
+    chunks: chunks.map((chunk) => {
+      let tokens = [];
+      try {
+        tokens = rootTokens(chunk.css);
+      } catch {}
+      return { ...chunk, tokens };
+    })
+  };
+}
+async function bookTokenEdits(projectDir, target, updates) {
+  const { manifest } = await loadManifestWithPath(projectDir);
+  const sheets = await bookSheets(projectDir, Array.isArray(manifest.styles) ? manifest.styles : undefined);
+  const at = sheets.indexOf(path.resolve(projectDir, target));
+  if (at < 0) {
+    throw new Error(`${relDisplay(projectDir, path.resolve(projectDir, target))} is not one of the book's stylesheets.`);
+  }
+  const before = await Promise.all(sheets.map(readText));
+  let after;
+  try {
+    after = applyTokenUpdates(before, at, updates);
+  } catch (error) {
+    const e = error;
+    const i = e.source === undefined ? -1 : before.indexOf(e.source);
+    if (i < 0 || !e.reason)
+      throw error;
+    throw new Error(`Couldn't read ${relDisplay(projectDir, sheets[i])}${e.line ? ` (line ${e.line})` : ""}: ${e.reason}.`);
+  }
+  return sheets.flatMap((file, i) => after[i] === before[i] ? [] : [{ path: file, content: after[i] }]);
+}
 export {
   whenGitIdle,
   validateProjectExtensions,
@@ -271,6 +495,7 @@ export {
   readManifestFields,
   readExtensionMeta,
   readExtensionCss,
+  readBookCss,
   publishTargetFor,
   publishProviderFor,
   publishCredentialKey,
@@ -285,6 +510,7 @@ export {
   log,
   loadManifestWithPath,
   loadManifest,
+  listVersionChanges,
   listSnippets,
   listRevisions,
   listRepoBooks,
@@ -352,6 +578,7 @@ export {
   checkCss,
   capabilitiesFor,
   bundledExtension,
+  bookTokenEdits,
   autoSyncDelayMs,
   autoSnapshotDelayMs,
   assertMilestone,

package/dist/lib/book-css.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The book's stylesheet as Book setup's design settings see it, and their one
+ * writer (#454).
+ *
+ * What the settings show is what the build assembles: core's CSS, every
+ * enabled extension's CSS — its stylesheet files and its `css` export,
+ * through the same loader the build uses, each in its cascade layer — then
+ * every one of the book's own `styles:` sheets, in the order
+ * `assembleCssChunks` gives them. A file's chunk is the file as written, so a
+ * value reads back as the author typed it: the build's inlining (fonts and
+ * images embedded, local `@import`s followed) is left out here.
+ *
+ * Writes go to the book's own `styles:` sheets only, never to an extension's
+ * files or a sheet the build does not use, with a postcss edit
+ * (`root-tokens.ts`).
+ */
+import { type CssChunk } from "./markdown/assemble.ts";
+import { type RootToken, type TokenUpdate } from "./root-tokens.ts";
+export type { RootToken, TokenUpdate } from "./root-tokens.ts";
+export type { CssChunk, CssChunkOrigin } from "./markdown/assemble.ts";
+/** One chunk of the book's stylesheet and the root-level custom properties it declares. */
+export interface BookCssChunk extends CssChunk {
+    /**
+     * Its root-level `:root` custom properties, in source order (`@internal`
+     * ones left out). Empty for a chunk postcss cannot parse: the print-safety
+     * check reports that one.
+     */
+    tokens: RootToken[];
+}
+/** The book's stylesheet, in cascade order. */
+export interface BookCss {
+    /** Joined with blank lines, the chunks cascade as the built book's stylesheet does. */
+    chunks: BookCssChunk[];
+}
+/** One stylesheet the token writer changed: its absolute path and new text. */
+export interface StylesheetEdit {
+    path: string;
+    content: string;
+}
+/**
+ * The book's stylesheet as ordered chunks tagged with their origin, each with
+ * its root-level custom properties. An extension that cannot load (not
+ * downloaded yet, a broken folder) is left out, as the live preview leaves it
+ * out; Book setup's Extensions tab reports it. Throws for a manifest the
+ * build would refuse.
+ */
+export declare function readBookCss(projectDir: string): Promise<BookCss>;
+/**
+ * Apply token edits to the book's own stylesheets with postcss
+ * (`applyTokenUpdates`): a token is changed in place in the last of them that
+ * declares it at root level, and a new one is added to the `:root` of
+ * `target`, which must be one of them. A removal takes the token out of all
+ * of them. Returns the sheets that change, with their new text, for the
+ * caller to write; nothing is written here.
+ */
+export declare function bookTokenEdits(projectDir: string, target: string, updates: TokenUpdate[]): Promise<StylesheetEdit[]>;

package/dist/lib/markdown/assemble.d.ts

@@ -167,6 +167,64 @@ export interface AssembleBookHtmlOptions {
      */
     onImageRefs?: (refs: string[]) => void;
 }
+/**
+ * Split a stylesheet into everything but its `@page` rules, and its `@page`
+ * rules, which the caller writes after it, unlayered, in source order. A
+ * rule inside an `@layer` loses that layer; one inside `@media` or
+ * `@supports` keeps the condition. CSS postcss cannot read is left as it was.
+ *
+ * Chromium ranks `@page` declarations by cascade layer before page name, so a
+ * layered `@page full { margin: 0 }` lost to the manifest's unlayered
+ * `@page { margin }` on its own pages, while the engine's reader, which
+ * ignores layers, kept it (#454). So no `@page` rule is written inside a
+ * layer — core's, an extension's or one in a layer the book declares —
+ * except core's 1in default (`defaultPageMarginCss`), which must lose to all
+ * of them.
+ * Unlayered, page rules cascade by page selector, then order: a named page
+ * keeps its margins, and the book's own sheet and the manifest, written
+ * later, still win on the pages they share with it.
+ */
+export declare function liftPageRules(css: string): {
+    layered: string;
+    pages: string;
+};
+/** Where one chunk of a book's stylesheet comes from. */
+export type CssChunkOrigin = {
+    kind: "core";
+}
+/** One extension's CSS: `file` (project-relative) for one of its stylesheets, none for its `css` export. */
+ | {
+    kind: "extension";
+    name?: string;
+    layer?: string;
+    file?: string;
+}
+/** One of the book's own `styles:` sheets (project-relative). */
+ | {
+    kind: "book";
+    file?: string;
+};
+/** One piece of a book's stylesheet, tagged with where it comes from. */
+export interface CssChunk {
+    origin: CssChunkOrigin;
+    css: string;
+}
+/**
+ * A book's stylesheet as ordered chunks, each tagged with its origin, in
+ * cascade order (see the note where {@link assembleBookHtml} calls this).
+ * Joined with blank lines, the chunks are the `<style data-project-css>`
+ * block that function writes; it passes the extensions' CSS and the book's
+ * whole, one chunk each. Book setup's design settings pass them one extension
+ * file and one book sheet at a time, so each setting can say where it comes
+ * from (`book-css.ts`).
+ */
+export declare function assembleCssChunks(opts: {
+    printArea?: PrintAreaSource;
+    /** The extensions' CSS, already in their cascade layers, in `extensions:` order. */
+    extensions?: CssChunk[];
+    /** The book's own stylesheets, in `styles:` order. */
+    book?: CssChunk[];
+}): CssChunk[];
 /**
  * Assemble a single `book.html` string from the given markdown files.
  *

package/dist/lib/publish/google-drive.d.ts

@@ -38,17 +38,25 @@ export interface DriveFolder {
  * page — an author with more than one page of app-created folders would
  * otherwise see the destinations picker silently miss folders past the
  * first 100. (`ensureFolder`'s find-by-name lookup uses its own single
- * server-side query, {@link findFolderByName} below, and doesn't paginate.) */
+ * server-side query, {@link findFoldersByName} below, and doesn't paginate.) */
 export declare function listFolders(fetchImpl: typeof fetch, accessToken: string): Promise<DriveFolder[]>;
-/** Look up one folder by id (for verifying a manifest-recorded `folderId`
- * still exists and isn't trashed). Returns null when it's gone. */
+/** Look up one folder by id (for verifying a recorded `folderId` is reachable
+ * with this account). Returns null when it isn't: trashed or deleted, or never
+ * opened through Gutterpress by this account — `drive.file` answers 404 for a
+ * folder this connection can't see, so the cases are one (#452). */
 export declare function getFolderById(fetchImpl: typeof fetch, accessToken: string, folderId: string): Promise<DriveFolder | null>;
 /** Create a folder at My Drive root. */
 export declare function createFolder(fetchImpl: typeof fetch, accessToken: string, name: string): Promise<DriveFolder>;
+/** App-visible folders with exactly this name, most recently modified first,
+ * at most `limit` of them — a single server-side query (the same `q=` pattern
+ * as {@link findFileInFolder}), not a client-side scan of every app-created
+ * folder. `ensureFolder` asks for one; a caller that must know whether
+ * several share the name (#452: the CLI says which it used) asks for two. */
+export declare function findFoldersByName(fetchImpl: typeof fetch, accessToken: string, name: string, limit?: number): Promise<DriveFolder[]>;
 /** Find-or-create a folder by name at My Drive root (D5's name-resolution
  * path, used when the manifest has no recorded `folderId` yet). One query,
  * not a client-side scan of every app-created folder — see
- * {@link findFolderByName}. */
+ * {@link findFoldersByName}. */
 export declare function ensureFolder(fetchImpl: typeof fetch, accessToken: string, name: string): Promise<DriveFolder>;
 export interface DriveFile {
     id: string;

package/dist/lib/publish/manifest-publish.d.ts

@@ -25,6 +25,12 @@ export declare function setPublishProviderConfig(projectDir: string, providerId:
  *   override). A folder inside the book is shared, and is written relative to
  *   it (an absolute in-book path is rewritten) so it means the same thing on
  *   every computer. An absolute path is never written to the manifest.
+ * - their own Google Drive folder for the book (`myFolderId`, `myFolder`; #452),
+ *   chosen when the book's folder is out of their reach or just for them. It is
+ *   recorded with the book's folder it stands in for (`myFolderFor`: the
+ *   manifest's `folderId`, else its `folder` name) and the account it was
+ *   chosen with (`myFolderAccount`), so it lapses when either changes (see
+ *   providers/gdrive.ts). Clearing `myFolderId` clears the whole record.
  *
  * Only the values passed are classified; the manifest is not rewritten unless
  * one of them changes it. Empty values clear. Returns the settings as the

package/dist/lib/publish/providers/gdrive-folder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Which Google Drive folder one person publishes to (#452), for the `gdrive`
+ * provider (gdrive.ts). The book's folder in the manifest is the team's; a
+ * person whose Google connection can't reach it publishes to a folder of their
+ * own, kept in their private store for the book, and that folder stands in for
+ * the book's only while the book's folder and their account are the ones it
+ * was chosen for.
+ */
+import { type DriveFolder } from "../google-drive.ts";
+import type { PublishDestinationStatus, PublishProduct, PublishRequest } from "../types.ts";
+/** Default folder name when the manifest sets neither `folder` nor
+ * `folderId` (D5, ratified: one shared "Gutterpress" folder, not
+ * per-book-title folders). */
+export declare const DEFAULT_FOLDER_NAME = "Gutterpress";
+/**
+ * Where this person publishes (#452). The book's folder is the team's: an id,
+ * checked with the account this person publishes with (`drive.file` answers 404
+ * for a folder it can't see, so "not shared with Gutterpress", "another
+ * account" and "trashed" are one case), or a name, which each person finds or
+ * creates in their own Drive. Their own folder, from their private store,
+ * stands in for it while it was chosen for the book's current folder and with
+ * the account they publish with now; one recorded against another folder or
+ * account no longer applies, and is dropped once the book's folder is
+ * reachable. Never writes the manifest or creates a folder.
+ */
+export declare function resolveFolder(req: PublishRequest, accessToken: string): Promise<PublishDestinationStatus>;
+/** The folder an upload goes to. An unreachable one fails, naming it and how
+ * to publish elsewhere: publishing never creates a folder in its place. */
+export declare function uploadFolder(where: PublishDestinationStatus, fetchImpl: typeof fetch, accessToken: string): Promise<PublishProduct>;
+export declare function toDestination(folder: DriveFolder): PublishProduct;

package/dist/lib/publish/run-publish.d.ts

@@ -10,6 +10,11 @@ export interface RunPublishOptions {
     artifactPath?: string;
     /** Stop after preflight — report issues without contacting the platform. */
     dryRun?: boolean;
+    /**
+     * Provider settings for this run only, laid over the saved ones and never
+     * written anywhere: the CLI's `--folder-id` / `--folder` (#452).
+     */
+    settings?: Record<string, string>;
     /**
      * The provider, when the caller has already resolved it (the CLI does, to
      * map a failed restore to its own exit code): no second lookup or restore.
@@ -39,7 +44,7 @@ export interface RunPublishResult {
  * with a preflight error over one bad manifest field.
  */
 export declare function resolvePublishFormat(info: PublishProviderInfo, providerConfig: Record<string, unknown>): PublishArtifactFormat;
-type RequestOptions = Pick<RunPublishOptions, "projectDir" | "providerId" | "manifestPath" | "artifactPath">;
+type RequestOptions = Pick<RunPublishOptions, "projectDir" | "providerId" | "manifestPath" | "artifactPath" | "settings">;
 /**
  * Resolve the {@link PublishRequest} for a BUILT-IN provider from the
  * project's manifest — for hosts that call individual provider methods

package/dist/lib/publish/types.d.ts

@@ -206,12 +206,13 @@ export interface PublishDeps {
     credentialAccount?: string;
     /**
      * The person's PRIVATE publishing values for a book (see
-     * {@link PublishSelectionsStore}): which saved account to use and an output
-     * folder outside the book. When given, they win over the manifest's
-     * `publish.<id>` values in every request. Absent (the CLI today): the
-     * manifest alone.
+     * {@link PublishSelectionsStore}): which saved account to use, an output
+     * folder outside the book, and their own Drive folder when the book's is out
+     * of their reach (#452). When given, they win over the manifest's
+     * `publish.<id>` values in every request, and a provider may drop one that
+     * no longer applies. Absent (the CLI today): the manifest alone.
      */
-    selections?: Pick<PublishSelectionsStore, "settings">;
+    selections?: Pick<PublishSelectionsStore, "settings" | "setSettings">;
 }
 /**
  * The TokenStore key for a publishing provider credential. Named accounts use a
@@ -252,6 +253,50 @@ export interface PublishProduct {
     title: string;
     url?: string;
 }
+/**
+ * Where one person publishes among a provider's destinations, and whether they
+ * must choose one (#452, gdrive's folders). The book's destination is the
+ * team's, in the manifest; a person whose account can't reach it chooses their
+ * own, kept in their private settings for the book.
+ */
+export type PublishDestinationStatus = 
+/** The book has no destination yet: the first choice is the book's. */
+{
+    state: "unset";
+}
+/** The book's destination, reachable with this person's account. */
+ | {
+    state: "book";
+    destination: PublishProduct;
+}
+/** The book names its destination by name only: each person's own of that
+ *  name. `destination` is this account's most recently changed one (absent:
+ *  it is created on the first publish); `several` when more share the name. */
+ | {
+    state: "by-name";
+    name: string;
+    destination?: PublishProduct;
+    several: boolean;
+}
+/** This person's own destination stands in for the book's. */
+ | {
+    state: "mine";
+    destination: PublishProduct;
+    book: {
+        title: string;
+        reachable: boolean;
+    };
+}
+/** Out of reach with this person's account: the book's destination, or their
+ *  own (`mine`, its title) when they have one. They must choose another. */
+ | {
+    state: "unreachable";
+    book: {
+        title: string;
+        reachable: boolean;
+    };
+    mine?: string;
+};
 /** Listing metadata for {@link PublishProvider.updateListing}. */
 export interface PublishListingMetadata {
     title?: string;
@@ -304,6 +349,8 @@ export interface PublishProvider {
     listDestinations?(req: PublishRequest): Promise<PublishProduct[]>;
     /** Create a new destination (gdrive: a Drive folder at My Drive root). */
     createDestination?(req: PublishRequest, name: string): Promise<PublishProduct>;
+    /** Where this person publishes now, and whether they must choose (#452). */
+    destinationStatus?(req: PublishRequest): Promise<PublishDestinationStatus>;
 }
 /**
  * Resolve the credential for a provider: the CI env var wins, then the token

package/dist/lib/remote-auth/converge-merge.d.ts

@@ -29,11 +29,11 @@ export interface ConvergeResult {
     keptBothFiles: KeptBothFile[];
 }
 /** Snapshot message for the equalization commit (driver-unreachable cases). */
-export declare const CONVERGE_PREPARE_MESSAGE = "Getting your changes ready to combine with the online version";
+export declare const CONVERGE_PREPARE_MESSAGE = "Getting your changes ready to combine with the online copy's changes";
 /** Snapshot message for the post-merge restore commit (kept-both/edits). */
-export declare const CONVERGE_RESTORE_MESSAGE = "Kept both versions of the files that can't be combined";
+export declare const CONVERGE_RESTORE_MESSAGE = "Kept both takes of the files that can't be combined";
 /** The merge commit message. */
-export declare const CONVERGE_MERGE_MESSAGE = "Combined your changes with the online version";
+export declare const CONVERGE_MERGE_MESSAGE = "Combined your changes with the online copy's";
 /**
  * diff3 merge that NEVER reports a conflict: clean hunks merge exactly like
  * git's default driver; clashing hunks keep BOTH versions inside standard

package/dist/lib/remote-auth/revisions.d.ts

@@ -33,6 +33,8 @@ export interface DeleteRevisionOptions extends OnlineOptions {
  *  3. rename on this computer — only a local failure is possible here, and it
  *     leaves the online copy renamed and this computer under the old name, still
  *     listed (the new name shows as online-only).
+ * A revision kept only in the online copy is renamed there (steps 1 and 2), with
+ * the tracking ref (what this computer last heard) standing in for its tip.
  * Offline or a rejected sign-in: nothing is renamed, anywhere.
  */
 export declare function renameRevision(options: RenameRevisionOptions): Promise<{
@@ -44,7 +46,9 @@ export declare function renameRevision(options: RenameRevisionOptions): Promise<
  * (a copy in the online copy stays, and shows as online-only); `everywhere`
  * removes it from the online copy first, then here — a failure online leaves
  * everything as it was, a failure here leaves it removed online and still
- * listed on this computer.
+ * listed on this computer. A revision kept only in the online copy has nothing
+ * here to remove: it is deleted from the online copy, as `everywhere` does, with
+ * the tracking ref (what this computer last heard) standing in for its tip.
  *
  * Nothing found only in the revision is deleted without a second look: when it
  * holds versions found in no other revision (and, unless deleted everywhere, not

package/dist/lib/remote-auth/sync-messages.d.ts

@@ -19,8 +19,8 @@ export declare const MSG_BUSY = "The online copy is changing very quickly right
  * VERSIONS are what broke, and (backing up always has an online copy, so this
  * always applies here) "Repair the online copy" is the way back.
  */
-export declare const MSG_HISTORY_UNREADABLE = "This book's versions can't be read, so backing up can't continue. Your writing is safe \u2014 every file is still here on this computer. Use \"Repair the online copy\" (in Book setup \u2192 Online copy) to get versions and backing up working again.";
-export declare const MSG_UNRELATED = "This book and the online copy have no versions in common, so they can't be combined. Either the online copy's address points at a different book, or this book's own versions were lost and started over. Your writing is safe \u2014 every file is still here on this computer. Check the online copy's address; if it is correct, use \"Repair the online copy\" (in Book setup \u2192 Online copy).";
+export declare const MSG_HISTORY_UNREADABLE = "This book's versions can't be read, so backing up can't continue. Your writing is safe \u2014 every file is still here on this computer. Use \"Repair the online copy\" in Book setup to get versions and backing up working again.";
+export declare const MSG_UNRELATED = "This book and the online copy have no versions in common, so they can't be combined. Either the online copy's address points at a different book, or this book's own versions were lost and started over. Your writing is safe \u2014 every file is still here on this computer. Check the online copy's address; if it is correct, use \"Repair the online copy\" in Book setup.";
 export declare const MSG_NO_REMOTE = "This book doesn't have an online copy yet.";
 export declare const MSG_SSH_REMOTE = "This book's online copy uses an SSH address (git@\u2026), which Gutterpress can't back up to. Switch it to the web (HTTPS) address to back up from here.";
 export declare const MSG_NO_BRANCH = "This book isn't on a named revision, so it can't be backed up right now.";