@taprootio/site-authoring 0.22.4 → 0.23.1

package/src/navigation-workspace.js

@@ -0,0 +1,73 @@
+import { HEX_DIGEST } from "./constants.js";
+import { SiteAuthoringError } from "./errors.js";
+import { NAVIGATION_FILE_NAME, readManifest, writeManifest } from "./workspace.js";
+
+/**
+ * The navigation tree's workspace baseline (TR01231).
+ *
+ * `nav push` replaces the whole tree, so a push built on a stale read would
+ * silently delete an item added in the app since. The manifest therefore
+ * records the revision the tree was read at, exactly as it does for the
+ * redirect map, and a push that cannot produce one refuses toward pull rather
+ * than guessing.
+ */
+
+export function isNavigationRevision(value) {
+  return typeof value === "string" && HEX_DIGEST.test(value);
+}
+
+function pullRequired(message, field) {
+  return new SiteAuthoringError("nav.pull_required", message, { field });
+}
+
+/** The manifest entry `pull` writes for a freshly read tree. */
+export function navigationManifestEntry({ navItems, revision }) {
+  return { file: NAVIGATION_FILE_NAME, items: navItems.length, ...(isNavigationRevision(revision) ? { revision } : {}) };
+}
+
+/** The recorded revision, or a refusal that says to pull. */
+export function requireNavigationBaseline(manifest) {
+  const navigation = manifest.navigation;
+  if (navigation === null || typeof navigation !== "object" || Array.isArray(navigation)) {
+    throw pullRequired(
+      "The pull manifest does not record the navigation tree. Run 'taproot-site pull' again.",
+      "navigation",
+    );
+  }
+  if (!isNavigationRevision(navigation.revision)) {
+    throw pullRequired(
+      "The pull manifest records no navigation revision, so a push could not tell whether the tree changed on the "
+        + "site since. Run 'taproot-site pull' again.",
+      "navigation.revision",
+    );
+  }
+  return navigation.revision;
+}
+
+/** The refusal for a tree that moved since the pull; nothing was written. */
+export function navigationMovedRefusal() {
+  return new SiteAuthoringError(
+    "nav.concurrent_modification",
+    "The navigation changed on the site after this workspace read it, so nothing was written. Keep a copy of the "
+      + `edited ${NAVIGATION_FILE_NAME}, run 'taproot-site pull' to refresh it, re-apply the edits, and push again.`,
+    { field: "revision" },
+  );
+}
+
+/**
+ * Records the revision the site reported after a successful save, so the next
+ * push is fenced against that state rather than the one before it.
+ */
+export async function advanceNavigationManifest(workspaceDir, siteId, { navItems, revision }) {
+  const manifest = await readManifest(workspaceDir, siteId);
+  requireNavigationBaseline(manifest);
+  if (!isNavigationRevision(revision)) {
+    throw new SiteAuthoringError(
+      "api.navigation_contract",
+      "Taproot returned a navigation tree whose revision could not be recorded.",
+      { field: "revision" },
+    );
+  }
+  manifest.navigation = navigationManifestEntry({ navItems, revision });
+  await writeManifest(workspaceDir, manifest);
+}

package/src/presentation-reference.js

@@ -421,6 +421,7 @@ export function getThemeReference() {
       "Check the filled action before anything else looks finished. Its ramp stop is chosen by the engine near a mid-band target rather than named by the theme, so seating the ramp — the remedy for every other anchored token — cannot move it, and declaring an action role does not either. The only lever is pinning semanticMappings.actionBackground.",
       "A brand colour between roughly L 0.55 and L 0.83 cannot be a button surface at its own lightness: across that band no ink, not even pure black, reaches the Lc 75 APCA asks of a button label. Espalier then walks the label to the far end of the ramp and the button renders inverted — a dark surface carrying a pale label where the swatch wanted the opposite. Pin the stop just past the band instead. A gold at L 0.81 pinned to a tone at L 0.85 carries a dark label at Lc 76; the same gold left to the engine compiles to a brown one.",
       "Name a tone as a lowercase slug — gold-band, not goldBand. theme push refuses any other name, and refuses a mapping that names a tone its theme or context never declares.",
+      "Run taproot-site theme resolve (offline; add --scheme, --context, or --json) after every edit to see what the theme compiles to: for the root page and each context in both schemes, every semantic color as oklch and hex, whether it is compiled from the roles or pinned (origin compiled, pinned, inherited_pin), and the WCAG contrast of each ink-on-surface pair Espalier defines against AA (4.5:1 text, 3:1 large text and UI). A pair under AA is listed in flags as theme.contrast_text_below_aa with the field to edit; it never fails the run, so decide whether it is a deliberate choice. theme resolve --site shows the site's stored theme for comparison.",
       "theme push runs Espalier's fit report over the root and every context in both schemes and lists each finding as a warning reading 'fit lint <id>'; theme push --dry-run does the same and writes nothing, and validate does it for an offline fixture. Read the lints before calling a theme done: action-anchor-inversion names a filled action that rendered the opposite way round from the swatches it declares, apca-target-unmet names a pair enforcement could not rescue, and action-canvas-separation and link-hover-ordering cover an action lost in its canvas and a hover weaker than its link. A lint is a warning, not a refusal, so a push still goes through with one — the lints are what tell an agent the design did not survive the compile. Contrast and status-color warnings end with 'Nearest passing value: …' when the CLI finds one: it applied that value to a copy of the theme and checked that the warning clears without raising another, so start there and check again. validate and theme push refuse a font weight a catalog family has no face for (theme.font_weight_unavailable), because the publish would fail, and name the nearest weight it has.",
       "Add named contexts for whole zones, including inverted zones, and rebind lightness when the zone changes brightness. A context that declares its own action needs its own actionBackground pin: without one it compiles at the engine's mid-band stop, and where the root is pinned it carries the root's pin instead, whatever action colour the context declares.",
       "Tune typography, type/space ratios, radii, and viewport interpolation as one layout system.",

package/src/redirects-contract.js

@@ -1,3 +1,4 @@
+import { HEX_DIGEST } from "./constants.js";
 import { SiteAuthoringError } from "./errors.js";
 import { RUNTIME_MIRROR_PATH_REASON } from "./reserved-paths.js";
 import {
@@ -77,7 +78,7 @@ export const REDIRECT_LIMITS = Object.freeze({
 // hide the mistake.
 const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/u;
 const ENTRY_KEYS = new Set(["path", "kind", "target", "status", "origin"]);
-const SHA256 = /^[0-9a-f]{64}$/u;
+const SHA256 = HEX_DIGEST;
 
 
 /** Whether the value is a redirect-map revision as the server mints one. */

package/src/redirects-workspace.js

@@ -5,8 +5,8 @@ import { readManifest, writeManifest } from "./workspace.js";
 /**
  * The redirect map's workspace baseline (TR00702).
  *
- * `nav.json` needs no baseline because navigation is last-write-wins; the
- * redirect map cannot be, because it holds entries nobody typed. Every page and
+ * Navigation records a revision the same way (`navigation-workspace.js`). The
+ * redirect map in particular cannot be last-write-wins, because it holds entries nobody typed. Every page and
  * tag rename records one, so a whole-map push built on a stale read would
  * delete the entry that keeps the renamed page's old URL alive. The manifest
  * therefore records the revision the map was read at, exactly as it records the

package/src/reference-help.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 
-import { CLI_BINARY_NAME, LIMITS } from "./constants.js";
+import { CLI_BINARY_NAME, LIMITS, STAGING_REVIEW_SESSION_NOTE } from "./constants.js";
 import {
   canonicalizeComponentData,
   COMPONENT_TYPES,
@@ -88,7 +88,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 40;
+export const REFERENCE_VERSION = 41;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -578,7 +578,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "runtime the page's bootstrap declares are fetched (an authored reference to any other host is content, "
       + "not delivery), local-only references (localhost, *.test, *.local) are reported rather than fetched, a "
       + "redirect Location that could reflect a credential is withheld, bodies are read up to a fixed bound, "
-      + "member-only content is not exercised, and nothing is purged, republished or rolled back.",
+      + "member-only content is not exercised, and nothing is purged, republished or rolled back. A staging check "
+      + "mints its own handoff, which ends an earlier review link minted with the same key (see 'help preview').",
       "Verdicts: delivered (no findings), degraded (every route served and the runtime is compatible, "
       + "but an asset, link or browser load did not match), failed (a route or the runtime did not deliver).",
     ]),
@@ -614,6 +615,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "the variants yourself with any image tool (a transparent logo at the highest resolution you have, a square favicon); there is no "
       + "recolor, crop or SVG upload command. Upload each with media upload, then assign lightLogoId and darkLogoId "
       + "(and brand.faviconId) from the image ids .taproot-site-media.json records for those files, so each scheme carries the artwork that reads on its header.",
+      `See the compiled colors: ${CLI_BINARY_NAME} theme resolve prints, offline, every semantic color Espalier compiles `
+      + "from the pair for each scheme and context, whether each is compiled from the roles or pinned, and the contrast "
+      + "of every ink-on-surface pair, with a flag for each one under WCAG AA. Run it after each theme edit, in both "
+      + "schemes, instead of discovering the result on staging; add --json to branch on it.",
       `Validate offline: ${CLI_BINARY_NAME} validate checks the whole workspace at once — the complete pair, the `
       + "appearance files, the footer, every page, navigation and redirects — against the contracts the site enforces, "
       + "lists every problem in error.problems, and warns when a semanticMappings pin repeats the default on a token "
@@ -635,7 +640,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "a single-use handoff in stagingPreview.url (on a managed Docs site too). Open it once, then use the site's "
       + "theme toggle to check both schemes: text, headings, links and hover, actions and focus, the header logos, the "
       + "favicon. When a requested handoff could not be minted, stagingPreview.reason says why and staging review mints "
-      + "another (add --path <page> to open it on the page under review). A page draft is "
+      + "another (add --path <page> to open it on the page under review). The review session lasts five minutes: "
+      + "see 'help preview' for what ends it. A page draft is "
       + "not needed to review a presentation change; preview page renders one persisted draft and is a different tool.",
       `Promote only after review: ${CLI_BINARY_NAME} deploy --production promotes the completed staging deployment. `
       + "Never use production to discover what staging should have shown.",
@@ -656,13 +662,18 @@ const WORKFLOW_REFERENCES = Object.freeze({
   }),
   nav: Object.freeze({
     title: "Navigation workspace contract",
-    summary: "nav push replaces the complete tree in nav.json; item IDs are author-minted canonical lowercase UUIDs.",
+    summary: "nav push replaces the complete tree in nav.json, fenced by the revision pull recorded; item IDs are author-minted canonical lowercase UUIDs.",
     usage: `${CLI_BINARY_NAME} nav push`,
     details: Object.freeze([
       "nav.json is { siteId, navItems }, not a bare array. Defaults are left out: an item has no resourceId or "
       + "externalUrl unless its kind uses one, and no children when it has none. pull and nav push both write that "
       + "form (nav push rewrites the file after it saves), and either form is accepted on the way in, so a pull after "
       + "a push shows no change you did not make.",
+      "nav push is fenced by the navigation revision that pull recorded in the manifest (navigation.revision), as "
+      + "theme push, footer push and redirects push are fenced by theirs. A tree edited in the app since is refused "
+      + "with nav.concurrent_modification and nothing is written: keep a copy of nav.json, run pull, re-apply the "
+      + "edits, and push again. A manifest with no navigation revision is refused with nav.pull_required; run pull. "
+      + "A successful push records the revision it saved, so the next push is fenced against that state.",
       "kind is NAV_ITEM_KIND_PAGE, NAV_ITEM_KIND_EXTERNAL_URL, or NAV_ITEM_KIND_GROUP_HEADER.",
       "PAGE uses resourceId from .taproot-site-manifest.json, never pageId or path.",
       "EXTERNAL_URL uses externalUrl; GROUP_HEADER has no target; every kind may carry children.",
@@ -704,7 +715,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "two-minute handoff, minted after checks. It is emitted only in final JSON, excluded from progress and "
       + "GITHUB_OUTPUT; keep it private. Without it, stagingPreview.reason is staging.handoff_not_requested and "
       + "'staging review' mints one. The staging cookie lasts five minutes and remains subject to current "
-      + "site/host/credential permission.",
+      + "site/host/credential permission. Each run mints its own handoff, which ends an earlier review link "
+      + "minted with the same key (see 'help preview').",
       `${REDIRECTS_FILE_NAME} is { siteId, revision, entries }, not a bare array. 'redirects pull' writes it and `
       + "records the revision in .taproot-site-manifest.json; 'pull' writes it too.",
       "An entry is { path, kind, target, status }. kind is 'redirect' (the default) or 'gone'; a gone entry "
@@ -934,6 +946,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "staging review for one, or pass --handoff to get a fresh single-use handoff in stagingPreview.url, minted "
       + "after the headless redirect checks. staging review --path <page> (and --review-path <page> beside --handoff) "
       + "opens the review on that page instead of the home page. Handoffs never go to GITHUB_OUTPUT.",
+      `Review session: ${STAGING_REVIEW_SESSION_NOTE} Once the session has ended, run staging review again for a `
+      + "fresh link, or stay signed in to the Taproot app in a browser whose account can preview the site, to review longer.",
       "On a managed Docs site deploy --staging stages settings only: run staging review (or deploy --staging "
       + "--handoff) and open the URL once, then use the site's theme toggle to review both schemes; no page draft is "
       + "needed to preview a presentation change. When a requested handoff can't be minted the result carries "

package/src/theme-resolve.js

@@ -0,0 +1,252 @@
+import { parseTheme, SEMANTIC_COLOR_NAMES, TOKEN_PAIRINGS } from "@taprootio/espalier/shared/theme";
+
+import { SiteAuthoringError } from "./errors.js";
+import { loadEspalierShared } from "./espalier-shared.js";
+import { validateAndEncodeThemePair } from "./theme-validation.js";
+
+/**
+ * `theme resolve` (TR01228): the colors Espalier compiles from a stored theme,
+ * with the contrast of every ink-on-surface pairing it defines.
+ *
+ * Nothing here compiles a color. The fit report suite is the same compile
+ * `theme push` lints and the page renders through (`computeThemeProperties`,
+ * and `resolveContextTheme` for each context), so a resolved value cannot
+ * disagree with the render. This module only reads that result and measures
+ * it.
+ */
+
+export const THEME_STYLES_FILE = "settings/taproot-styles.json";
+
+// WCAG 2.x AA. Espalier sizes its pairings by APCA target: Lc 90 and 75 are
+// body and 16px+ text, Lc 60 is the 24px+ and UI tier, which is what AA calls
+// large text and non-text contrast.
+export const AA_TEXT_RATIO = 4.5;
+export const AA_LARGE_RATIO = 3;
+const LARGE_TEXT_LC = 60;
+
+export const CONTRAST_TEXT_BELOW_AA = "theme.contrast_text_below_aa";
+
+const THEME_SCHEMES = Object.freeze(["light", "dark"]);
+
+let engines;
+
+/** The fit report and color engine are Espalier modules beside the exported theme module (see espalier-shared.js). */
+function loadEngines() {
+  engines ??= Promise.all([
+    loadEspalierShared("theme-fit-report.js"),
+    loadEspalierShared("color-engine.js"),
+  ]).then(([fit, color]) => ({ fit, color }));
+  return engines;
+}
+
+function channelByte(color, value) {
+  return Math.round(color.clampChannel(value) * 255);
+}
+
+/** The sRGB the engine gamut-maps a compiled color to, as channels in 0..1 and as #rrggbb. */
+function toSrgb(color, value) {
+  const parsed = color.parseCssColor(value);
+  if (parsed === null) return undefined;
+  const srgb = color.oklchToSRGB(color.gamutMapToSRGB(parsed));
+  const hex = `#${[srgb.r, srgb.g, srgb.b].map((channel) => channelByte(color, channel).toString(16).padStart(2, "0")).join("")}`;
+  return { parsed, srgb, hex };
+}
+
+function relativeLuminance(color, srgb) {
+  const linear = (channel) => color.gammaToLinear(color.clampChannel(channel));
+  return 0.2126 * linear(srgb.r) + 0.7152 * linear(srgb.g) + 0.0722 * linear(srgb.b);
+}
+
+/** WCAG contrast ratio of two compiled colors, unrounded. */
+function wcagRatio(color, first, second) {
+  const [lighter, darker] = [relativeLuminance(color, first.srgb), relativeLuminance(color, second.srgb)]
+    .sort((left, right) => right - left);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// Shown ratios round down, so a pair 0.004 short of AA never displays as 4.50.
+function floorTo(value, places) {
+  const scale = 10 ** places;
+  return Math.floor(value * scale + 1e-9) / scale;
+}
+
+function origin(token) {
+  if (token.explicit === "declared") return "pinned";
+  if (token.explicit === "inherited") return "inherited_pin";
+  return "compiled";
+}
+
+function surfaceField(scheme, context) {
+  return context === null ? `${scheme}Theme` : `${scheme}Theme.contexts.${context}`;
+}
+
+/**
+ * The finding for one pair under AA: a stable code, and the theme field whose zone the author edits.
+ *
+ * There is one code. Espalier's enforcer walks an ink to the extreme that contrasts with its surface, so a
+ * large-text or UI pair never lands under 3:1 in a real theme and a second code could not be reached. `required`
+ * still says which minimum the pair missed.
+ */
+function contrastFlag(pair, scheme, context) {
+  return {
+    code: CONTRAST_TEXT_BELOW_AA,
+    area: "presentation",
+    file: THEME_STYLES_FILE,
+    field: surfaceField(scheme, context),
+    token: pair.token,
+    background: pair.background,
+    scheme,
+    context,
+    ratio: pair.ratio,
+    required: pair.required,
+    message: `${pair.token} on ${pair.background} is ${pair.ratio}:1; needs ${pair.required}:1.`,
+  };
+}
+
+function describeSurface(color, report, scheme, rootSurface) {
+  const context = report.surface === rootSurface ? null : report.surface;
+  const resolved = new Map();
+  const tokens = report.tokens.map((token) => {
+    const measured = toSrgb(color, token.resolved);
+    resolved.set(token.token, measured);
+    return {
+      token: token.token,
+      value: token.resolved,
+      hex: measured?.hex ?? null,
+      origin: origin(token),
+      source: token.source,
+      lightness: token.lightness,
+      // Only when APCA enforcement moved it off the requested value; absent is the usual case.
+      ...(token.adjusted ? { adjusted: true } : {}),
+    };
+  });
+  const pairs = [];
+  for (const [ink, pairing] of Object.entries(TOKEN_PAIRINGS)) {
+    const foreground = resolved.get(ink);
+    const background = resolved.get(pairing.bg);
+    if (foreground === undefined || background === undefined) continue;
+    const required = pairing.targetLc <= LARGE_TEXT_LC ? AA_LARGE_RATIO : AA_TEXT_RATIO;
+    const ratio = wcagRatio(color, foreground, background);
+    const lc = Math.abs(color.apcaContrast(foreground.parsed, background.parsed));
+    pairs.push({
+      token: ink,
+      background: pairing.bg,
+      ratio: floorTo(ratio, 2),
+      required,
+      aa: ratio >= required,
+      apcaLc: floorTo(lc, 1),
+      apcaTarget: pairing.targetLc,
+      apcaMet: lc >= pairing.targetLc,
+    });
+  }
+  const flags = pairs.filter((pair) => !pair.aa).map((pair) => contrastFlag(pair, scheme, context));
+  return {
+    surface: { context, tokens, pairs, pinned: tokens.filter((token) => token.origin !== "compiled").map((token) => token.token) },
+    flags,
+  };
+}
+
+/**
+ * The compiled colors of a stored light/dark pair. `scheme` and `context`
+ * narrow what is described, never what is validated or compiled: the pair is
+ * checked as a whole, as `theme push` checks it.
+ *
+ * Throws what `theme push` would throw for an incomplete or invalid theme, and
+ * a `theme.context_unknown` refusal for a context the theme does not declare.
+ */
+export async function resolveThemePair(lightTheme, darkTheme, { scheme, context } = {}) {
+  const { light, dark } = validateAndEncodeThemePair(lightTheme, darkTheme);
+  const { fit, color } = await loadEngines();
+  // The stored pair is encoded and parsed back, as theme push's fit lints do, so this is what the page resolves.
+  const suite = fit.themeFitReportSuite(parseTheme(light) ?? {}, parseTheme(dark) ?? {});
+  const contexts = suite.surfaces.filter((surface) => surface !== fit.ROOT_SURFACE);
+  if (context !== undefined && !contexts.includes(context)) {
+    throw new SiteAuthoringError(
+      "theme.context_unknown",
+      contexts.length === 0
+        ? `The theme declares no context named '${context}'; it declares none.`
+        : `The theme declares no context named '${context}'. Declared: ${contexts.join(", ")}.`,
+      { field: "context", alternatives: contexts },
+    );
+  }
+
+  const schemes = [];
+  const flags = [];
+  for (const name of THEME_SCHEMES) {
+    if (scheme !== undefined && scheme !== name) continue;
+    const surfaces = [];
+    for (const report of suite[name]) {
+      if (context !== undefined && report.surface !== context) continue;
+      const described = describeSurface(color, report, name, fit.ROOT_SURFACE);
+      surfaces.push(described.surface);
+      flags.push(...described.flags);
+    }
+    schemes.push({ scheme: name, surfaces });
+  }
+  const pairs = schemes.flatMap((entry) => entry.surfaces).flatMap((surface) => surface.pairs);
+  return {
+    contexts,
+    schemes,
+    flags,
+    contrast: {
+      pairs: pairs.length,
+      belowAa: pairs.filter((pair) => !pair.aa).length,
+      belowApca: pairs.filter((pair) => !pair.apcaMet).length,
+    },
+  };
+}
+
+const TOKEN_ORDER = new Map(SEMANTIC_COLOR_NAMES.map((name, index) => [name, index]));
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}
+
+function table(rows) {
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => String(row[column]).length)));
+  return rows.map((row) => `  ${row.map((cell, column) => pad(cell, widths[column])).join("  ").trimEnd()}`).join("\n");
+}
+
+/**
+ * The human table for a result. Tokens keep Espalier's own order, so a
+ * background and its layers read together; a pinned or inherited value is
+ * marked, and a pair under AA says so on its line.
+ */
+export function formatThemeResolve(result) {
+  const lines = [`Compiled colors from the ${result.source === "site" ? "site's" : "workspace"} theme.`];
+  for (const { scheme, surfaces } of result.schemes) {
+    for (const surface of surfaces) {
+      lines.push("", `${scheme} · ${surface.context === null ? "page (root)" : `context ${surface.context}`}`);
+      const tokens = [...surface.tokens].sort((left, right) => TOKEN_ORDER.get(left.token) - TOKEN_ORDER.get(right.token));
+      lines.push(table([
+        ["token", "value", "hex", "from"],
+        ...tokens.map((token) => [
+          token.token,
+          token.value,
+          token.hex ?? "-",
+          `${token.origin === "compiled" ? "" : `${token.origin.replace("_", " ")}: `}${token.source} @ ${token.lightness}${token.adjusted ? " (adjusted for contrast)" : ""}`,
+        ]),
+      ]));
+      lines.push("", table([
+        ["ink", "on", "ratio", "needs", "apca", ""],
+        ...surface.pairs.map((pair) => [
+          pair.token,
+          pair.background,
+          `${pair.ratio}:1`,
+          `${pair.required}:1`,
+          `Lc ${pair.apcaLc}/${pair.apcaTarget}`,
+          pair.aa ? "ok" : "BELOW AA",
+        ]),
+      ]));
+    }
+  }
+  const { belowAa, pairs } = result.contrast;
+  lines.push("", belowAa === 0
+    ? `All ${pairs} pairs meet WCAG AA.`
+    : `${belowAa} of ${pairs} pairs are below WCAG AA (flags: ${[...new Set(result.flags.items.map((flag) => flag.code))].join(", ")}).`);
+  if (result.omittedSurfaces !== undefined) {
+    const names = result.omittedSurfaces.items.map((entry) => `${entry.scheme}/${entry.context ?? "root"}`);
+    lines.push(`Not shown (result size): ${names.join(", ")}${result.omittedSurfaces.truncated ? ", and more" : ""}. Narrow with --scheme and --context.`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/transport.js

@@ -39,8 +39,8 @@ const ALLOWED_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
 // authoring mutations carry an idempotency key — TR00602 defined none — so a
 // replayed POST duplicates a page, a replayed PATCH re-applies an update over an edit
 // that landed in between, a replayed DELETE removes a resource the first
-// attempt already removed, and a replayed navigation PUT re-asserts a tree
-// after someone else changed it. An ambiguous mutation is reported as
+// attempt already removed, and a replayed navigation PUT, fenced by the revision it
+// presented, reports a false conflict once the first attempt has committed. An ambiguous mutation is reported as
 // ambiguous, never guessed at. The one PUT that *is* replayed is the
 // presigned whole-object upload in `upload()`, which writes immutable bytes
 // to one key and is therefore genuinely idempotent. Two POSTs have their own
@@ -51,6 +51,10 @@ const IDEMPOTENT_METHODS = new Set(["GET"]);
 
 /** An exchanged credential is renewed once it is this close to expiring. */
 const CREDENTIAL_RENEWAL_MARGIN_MILLISECONDS = 5 * 60_000;
+const GATEWAY_UPLOAD_ATTEMPTS = 4;
+const GATEWAY_CAPACITY_WINDOW_MILLISECONDS = 15_000;
+const UPLOAD_CAPACITY_HEADER = "x-taproot-upload-admission";
+const UPLOAD_CAPACITY_REFUSAL = "capacity-before-claim";
 
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 const RETRYABLE_RESPONSE_ERRORS = new Set([
@@ -965,15 +969,16 @@ export class SiteApiClient {
   }
 
   /**
-   * Performs one presigned whole-object PUT. The signed headers are echoed
+   * Performs a whole-object PUT. Signed S3 headers are echoed
    * exactly as the server returned them and are never recomputed: the values
    * are covered by the SigV4 signature, so a "helpfully" regenerated
    * Content-Type or an added header turns into an opaque S3 403. The bearer is
    * never forwarded — the signature is the authorization, and sending the
    * site key to an object store would leak it outside the reviewed origin.
    *
-   * The PUT of an immutable object is idempotent, so this is the one mutation
-   * shape that may be replayed.
+   * S3 create-only uploads retain their existing retry contract. A gateway
+   * capability is consumed once before the body is read. Only an explicit
+   * capacity refusal before that claim permits a bounded retry.
    */
   async upload({ url: uploadUrl, requiredHeaders } = {}, bodyBytes) {
     // A video original is streamed from disk: `{ byteLength, stream, timeoutMilliseconds }`,
@@ -1040,7 +1045,8 @@ export class SiteApiClient {
       names.add(normalizedName);
       headers.set(name, value);
     }
-    if (!headers.has("content-type") || !headers.has("content-length")) {
+    const gateway = headers.has("x-taproot-upload-capability");
+    if (!headers.has("content-type") || (!gateway && !headers.has("content-length"))) {
       throw new SiteAuthoringError(
         "upload.headers_invalid",
         "The signed upload capability is missing required content headers.",
@@ -1049,31 +1055,48 @@ export class SiteApiClient {
     // The declared length is bound into the signature, so a body of any other
     // size cannot succeed. Failing here names the real problem instead of
     // surfacing an S3 signature error.
-    if (headers.get("content-length") !== String(bodyBytes.byteLength)) {
+    if (gateway && (
+      url.origin !== this.apiOrigin
+      || !url.pathname.startsWith(this.apiPathPrefix)
+      || !/^\/api\/v1\/images\/uploads\/[0-9a-f-]{36}\/content$/u.test(url.pathname)
+      || url.search !== ""
+    )) {
+      throw new SiteAuthoringError("upload.contract_invalid", "Taproot returned an invalid gateway URL.");
+    }
+    if (!gateway && headers.get("content-length") !== String(bodyBytes.byteLength)) {
       throw new SiteAuthoringError(
         "upload.content_length_invalid",
         "The signed upload content length does not match the bytes being uploaded.",
       );
     }
 
-    for (let attempt = 0; attempt < LIMITS.uploadAttempts; attempt += 1) {
+    const maximumAttempts = gateway ? GATEWAY_UPLOAD_ATTEMPTS : LIMITS.uploadAttempts;
+    const startedAt = this.now();
+    const uploadDeadline = startedAt + ((streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds);
+    for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
+      if (this.signal?.aborted) throw cancelledError(false);
+      const remaining = uploadDeadline - this.now();
+      if (gateway && remaining <= 0) {
+        throw new SiteAuthoringError("upload.capacity_exhausted", "The image upload exhausted its attempt window.");
+      }
       let response;
+      const attemptSignal = operationSignal(
+        this.signal,
+        gateway ? remaining : (streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds,
+        this.timeoutSignal,
+      );
       try {
-        response = await this.fetch(url, {
+        response = await awaitWithSignal(this.fetch(url, {
           method: "PUT",
           redirect: "error",
-          signal: operationSignal(
-            this.signal,
-            (streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds,
-            this.timeoutSignal,
-          ),
+          signal: attemptSignal,
           headers,
           ...(streamed
             ? { body: Readable.toWeb(bodyBytes.stream()), duplex: "half" }
             : { body: bodyBytes }),
-        });
+        }), attemptSignal);
       } catch {
-        if (attempt + 1 < LIMITS.uploadAttempts && !this.signal?.aborted) {
+        if (!gateway && attempt + 1 < maximumAttempts && !this.signal?.aborted) {
           await this.sleep(delayForAttempt(attempt), this.signal);
           continue;
         }
@@ -1082,14 +1105,29 @@ export class SiteApiClient {
           "The whole-object upload ended without an authoritative response.",
         );
       }
-      await cancelBody(response);
+      await cancelBody(response, attemptSignal);
       if (response.status >= 200 && response.status < 300 && !response.redirected) return;
-      if (RETRYABLE_STATUS.has(response.status) && attempt + 1 < LIMITS.uploadAttempts) {
+      const capacityRefused = gateway && !response.redirected && response.status === HTTP_TOO_MANY_REQUESTS
+        && response.headers.get(UPLOAD_CAPACITY_HEADER) === UPLOAD_CAPACITY_REFUSAL;
+      const retryAfter = response.headers.get("retry-after") ?? "";
+      if (capacityRefused && /^[1-5]$/u.test(retryAfter) && attempt + 1 < maximumAttempts) {
+        const delay = Number(retryAfter) * 1000;
+        const capacityRemaining = Math.min(uploadDeadline, startedAt + GATEWAY_CAPACITY_WINDOW_MILLISECONDS) - this.now();
+        if (delay < capacityRemaining) {
+          // TR01295: the server guarantees that this rejected PUT did not
+          // claim the capability. Network failures and 5xx never retry it.
+          await awaitWithSignal(this.sleep(delay, this.signal), operationSignal(
+            this.signal, capacityRemaining, this.timeoutSignal,
+          ));
+          if (this.now() - startedAt < GATEWAY_CAPACITY_WINDOW_MILLISECONDS) continue;
+        }
+      }
+      if (!gateway && RETRYABLE_STATUS.has(response.status) && attempt + 1 < maximumAttempts) {
         await this.sleep(delayForAttempt(attempt), this.signal);
         continue;
       }
       throw new SiteAuthoringError(
-        RETRYABLE_STATUS.has(response.status) ? "upload.ambiguous" : "upload.rejected",
+        RETRYABLE_STATUS.has(response.status) && !capacityRefused ? "upload.ambiguous" : "upload.rejected",
         `The whole-object upload was rejected with HTTP ${response.status}.`,
         { status: `http:${response.status}` },
       );

package/src/verbs/approve.js

@@ -1,7 +1,7 @@
 import {
+  isGonePage,
   listSitePages,
   PAGE_STATUS_APPROVED,
-  PAGE_STATUS_DELETED,
   publishDrafts,
   withRefusalGuidance,
 } from "../api.js";
@@ -81,7 +81,7 @@ export async function approve(invocation) {
     }
     const pathOf = (summary) => normalizePagePath(summary.path) ?? summary.path;
     const candidates = pages.filter((summary) =>
-      summary.status !== PAGE_STATUS_DELETED
+      !isGonePage(summary)
       && summary.hasDraft
       && manifestByPageId.has(summary.pageId)
       && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
@@ -94,7 +94,7 @@ export async function approve(invocation) {
       const matched = new Set(candidates.map(pathOf));
       const unknown = [];
       for (const requested of [...requestedPaths].filter((value) => !matched.has(value)).sort()) {
-        const summary = pages.find((page) => page.status !== PAGE_STATUS_DELETED && pathOf(page) === requested);
+        const summary = pages.find((page) => !isGonePage(page) && pathOf(page) === requested);
         if (summary === undefined || !manifestByPageId.has(summary.pageId)) {
           unknown.push(displayPagePath(requested));
           continue;

package/src/verbs/deploy.js

@@ -28,6 +28,7 @@ import { HANDOFF_NOT_REQUESTED_PROGRESS, handoffNotRequested, inspectStagingPrev
 import { confirmStagingServed, readStagingReleaseBefore, unverifiedStagingServed } from "../staging-served.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
+import { STAGING_REVIEW_GUIDANCE } from "./staging-review.js";
 
 /**
  * When a redirect goes live (TR00702, TR00968, TR01236).
@@ -168,9 +169,6 @@ function reportReadiness(readiness) {
   };
 }
 
-const PRESENTATION_REVIEW_GUIDANCE = "Open the URL once in a browser, then switch the site's theme toggle between "
-  + "light and dark to review both schemes; no page draft is needed to preview a presentation change.";
-
 /**
  * Why a managed Docs staging handoff could not be minted, as a stable reason
  * the caller can act on. The recovery never points at production or at a host
@@ -217,8 +215,8 @@ function presentationHandoffUnavailable(error) {
 async function mintPresentationStagingHandoff(client, siteId, onProgress, now, returnPath) {
   try {
     const handoff = await mintStagingPreviewHandoff(client, siteId, { now, returnPath });
-    onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${PRESENTATION_REVIEW_GUIDANCE}`);
-    return { ...handoff, review: PRESENTATION_REVIEW_GUIDANCE };
+    onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${STAGING_REVIEW_GUIDANCE}`);
+    return { ...handoff, review: STAGING_REVIEW_GUIDANCE };
   } catch (error) {
     if (error instanceof SiteAuthoringError && !(error instanceof ApiError)) throw error;
     const unavailable = presentationHandoffUnavailable(error);