@taprootio/site-authoring 0.8.3 → 0.8.5

package/src/errors.js

@@ -91,6 +91,17 @@ export function sanitizeDiagnostic(value, fallback = "The operation failed.") {
   return [...clean].slice(0, LIMITS.diagnosticScalars).join("") || fallback;
 }
 
+/**
+ * The fixed wording every `theme.setting_missing` detail carries. A required
+ * key that is absent is exactly that: absence alone says nothing about when
+ * the key entered the contract, so the text never claims a later contract
+ * introduced it. The remedy names both truthful recoveries — restore the key
+ * locally, or refresh a workspace that is stale — without promising that a
+ * repeated pull repairs a server projection that already omits the key.
+ */
+export const MISSING_SETTING_MESSAGE =
+  "is required and absent (restore it locally, or run 'taproot-site pull' if this workspace is stale)";
+
 /**
  * The one error type this package throws. Every failure carries a stable
  * dotted code and an exit code: 2 for a usage fault the caller fixes by
@@ -111,7 +122,7 @@ export class SiteAuthoringError extends Error {
         .map((item) => ({
           code: item.code,
           field: sanitizeDiagnostic(item.field, "").slice(0, 200),
-          message: "is missing (added in a later contract; run taproot-site pull)",
+          message: MISSING_SETTING_MESSAGE,
         }))
       : undefined;
     this.previewDiagnostic = normalizePreviewDiagnostic(options.previewDiagnostic);

package/src/presentation-reference.js

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
 
+import { computeThemeProperties } from "@taprootio/espalier/shared/theme-properties";
+
 import {
   DATA_SERIES_KEYS,
   DEFAULT_DATA_RAMP_STEPS,
@@ -11,6 +13,7 @@ import {
   DEFAULT_DARK_THEME,
   DEFAULT_LIGHT_THEME,
   LIGHTNESS_KEYS,
+  mergeTheme,
   NESTED_THEME_KEYS,
   ROLE_NAMES,
   SEMANTIC_COLOR_NAMES,
@@ -92,13 +95,24 @@ function exampleTheme(defaults, scheme) {
       paper: "#fffaf4",
       midnight: "#21172b",
     },
-    roles: {
-      canvas: "primary",
-      ink: { color: "primary", heading: "anchor:midnight" },
-      accent: { color: "anchor:plum", text: "anchor:plum.text", hover: "anchor:plum.hover" },
-      action: { color: "anchor:plum", ink: "anchor:paper" },
-      structure: "primary",
-    },
+    // Contrasting on purpose: light headings sit in the dark anchor on the
+    // light canvas, dark headings in the paper anchor on the dark canvas. The
+    // pair is resolved and contrast-checked by assertPresentationExamples.
+    roles: scheme === "light"
+      ? {
+        canvas: "primary",
+        ink: { color: "primary", heading: "anchor:midnight" },
+        accent: { color: "anchor:plum", text: "anchor:plum.text", hover: "anchor:plum.hover" },
+        action: { color: "anchor:plum", ink: "anchor:paper" },
+        structure: "primary",
+      }
+      : {
+        canvas: "primary",
+        ink: { color: "primary", heading: "anchor:paper" },
+        accent: { color: "anchor:plum", text: "anchor:plum.hover", hover: "anchor:paper" },
+        action: { color: "anchor:plum", ink: "anchor:paper" },
+        structure: "primary",
+      },
     contexts: {
       inverted: {
         canvas: "anchor:midnight",
@@ -251,6 +265,69 @@ const THEME_GROUPS = Object.freeze([
   }),
 ]);
 
+/**
+ * How a role binding becomes a rendered token, in the order the resolver
+ * applies it. Stated once here so help theme, the walkthrough and the
+ * validation warnings describe the same model (TR00801, TR00806).
+ */
+export const ROLE_RESOLUTION = Object.freeze({
+  slots: Object.freeze({
+    canvas: Object.freeze([]),
+    ink: Object.freeze(["heading"]),
+    accent: Object.freeze(["text", "hover"]),
+    action: Object.freeze(["ink"]),
+    structure: Object.freeze([]),
+  }),
+  bindingForms: Object.freeze([
+    "A role takes one mapping source, or { color, ...slots } to bind its slots separately.",
+    "A geometric source (" + COLOR_SOURCES.filter((source) => !STATUS_COLOR_SOURCES.includes(source)).join(", ")
+    + ") is relative: it takes the seed hue through that family's angle and the token's lightness stop, so it moves "
+    + "with seedColor and the lightness ramp. A status family (" + STATUS_COLOR_SOURCES.join(", ")
+    + ") keeps its fixed hue from semanticHues (or its intents override) and does not move with seedColor.",
+    "anchor:<name> is absolute in hue and chroma: the anchor's declared colour supplies both, and the token's own "
+    + "lightness stop (with APCA enforcement) still sets its lightness. anchor:<name>.<slot> selects one of the "
+    + "anchor's declared slots (text, hover, ...) as that hue-and-chroma source and resolves the same way; neither "
+    + "form renders the declared colour verbatim.",
+    "Anchors resolve per scheme: the same anchor:<name> in lightTheme and darkTheme reads each scheme's own anchors "
+    + "table, so a dark scheme usually declares darker or lighter anchors under the same names.",
+  ]),
+  precedence: Object.freeze([
+    "Any mapping present in semanticMappings wins for its token, whether or not explicitMappingTokens names it: "
+    + "the shipped resolver overlays the stored mappings after compiling the roles. To let a role reach a token, "
+    + "delete the mapping; editing the marker alone does not unpin it. explicitMappingTokens records which mappings "
+    + "are authored pins and is what pull writes.",
+    "Otherwise the token is compiled from the roles, and an APCA contrast check may nudge an action or ink stop so "
+    + "the pair stays readable.",
+    "Otherwise the Espalier default mapping applies.",
+    "A context rebinds roles, lightness, tones and pins for one zone with the same precedence inside that zone.",
+  ]),
+});
+
+function themeLightness(value) {
+  const match = /^oklch\(\s*([0-9.]+)/u.exec(value ?? "");
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * The examples must render as contrasting pairs, not merely validate: a dark
+ * example whose headings resolve to a dark anchor on a dark canvas validated
+ * fine and read as a defect. Resolve both through Espalier and require the
+ * text, heading and link tokens to sit well away from the canvas lightness.
+ */
+function assertExampleContrast(theme, scheme) {
+  const properties = computeThemeProperties(
+    mergeTheme(scheme === "light" ? DEFAULT_LIGHT_THEME : DEFAULT_DARK_THEME, theme),
+    scheme,
+  );
+  const canvas = themeLightness(properties["--esp-color-background"]);
+  for (const token of ["--esp-color-text", "--esp-color-headings", "--esp-color-link", "--esp-color-action-text"]) {
+    const lightness = themeLightness(properties[token]);
+    if (canvas === undefined || lightness === undefined || Math.abs(lightness - canvas) < 0.4) {
+      throw new Error(`${scheme} theme example: ${token} (${properties[token]}) does not contrast with the canvas (${properties["--esp-color-background"]}).`);
+    }
+  }
+}
+
 export function getThemeReference() {
   const version = getEspalierVersion();
   return {
@@ -270,14 +347,15 @@ export function getThemeReference() {
       semanticColors: SEMANTIC_COLOR_NAMES,
       dataSeries: DATA_SERIES_KEYS,
     },
+    roleResolution: ROLE_RESOLUTION,
     workflow: [
-      "Run taproot-site pull and edit the complete light/dark pair it writes; never build a sparse theme from memory.",
+      "Run taproot-site pull and edit the complete light/dark pair it writes; never build a sparse theme from memory. pull resolves the stored theme over the same defaults every consumer renders, so a fresh workspace validates and every group carries its effective value.",
       "Define brand anchors first, then assign canvas, ink, accent, action, and structure roles in both schemes.",
       "Add named contexts for whole zones, including inverted zones, and rebind lightness when the zone changes brightness.",
       "Tune typography, type/space ratios, radii, and viewport interpolation as one layout system.",
       "Typography is per scheme on purpose: light and dark set their own moods, so a heading, body, or brand face that differs between them is a design choice, and theme push never warns about it.",
       "Retune danger/success/warning/info through intents without changing their meanings; design data palettes separately.",
-      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model.",
+      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model. pull keeps only authored pins there and lists them in explicitMappingTokens; a default mapping copied into the document becomes a pin and makes the role for that token inert.",
       "Run theme push, inspect warnings, then verify text, actions, focus states, and both schemes in authoring previews.",
     ],
     example: THEME_EXAMPLE,
@@ -333,7 +411,17 @@ export function getAppearanceReference() {
     imageReferences:
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
-      "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting.",
+      "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting. "
+      + "Prefer transparent PNG or WebP artwork with genuine alpha so the header background shows through, including "
+      + "inside letter counters. Avoid baked-in background rectangles unless the brand intentionally uses a badge. "
+      + "Keep padding tight and verify the delivered image preserves transparency. Logo style and coloration are "
+      + "project-specific: choose monochrome, an accent, or multiple colors to suit the brand, not a universal recipe. "
+      + "Keep the lettering readable and test the visible artwork against each header scheme.",
+    faviconContract:
+      "Include a favicon when designing a site: upload a square, simplified brand mark and set brand.faviconId "
+      + "in settings/brand.json, then run theme push; faviconUrl is a read-only projection. Do not shrink a full wordmark into a favicon. "
+      + "Inspect at 16 and 32 pixels in light and dark browser tabs; a deliberate contrasting badge can help a favicon "
+      + "remain recognizable independently of the header theme. Verify the published icon loads, not just the setting.",
     logoContrastContract:
       "Evaluate lightLogoId against the rendered light-scheme header and darkLogoId against the rendered dark-scheme "
       + "header at desktop and compact/mobile widths. Transparent pixels provide no contrast: inspect the visible mark, "
@@ -531,6 +619,8 @@ export function getFooterReference() {
 
 export function assertPresentationExamples() {
   validateAndEncodeThemePair(THEME_EXAMPLE.lightTheme, THEME_EXAMPLE.darkTheme);
+  assertExampleContrast(THEME_EXAMPLE.lightTheme, "light");
+  assertExampleContrast(THEME_EXAMPLE.darkTheme, "dark");
   validateFooterDocument(FOOTER_EXAMPLE);
 }
 
@@ -590,7 +680,15 @@ export function formatPresentationReference(reference) {
       + reference.themePaths.join(", ") + ")\nComplete pulled baseline required: yes\nNested merge groups: "
       + reference.nestedMergeGroups.join(", ") + "\n\nDesign workflow:\n"
       + reference.workflow.map((step, index) => "  " + (index + 1) + ". " + step).join("\n")
-      + "\n\nTheme groups:\n" + groups + "\n\nValid complete pair:\n"
+      + "\n\nRole slots:\n"
+      + Object.entries(reference.roleResolution.slots).map(([role, slots]) =>
+        "  " + role.padEnd(10) + (slots.length === 0 ? "color only" : "color, " + slots.join(", "))
+      ).join("\n")
+      + "\n\nHow a binding resolves:\n"
+      + reference.roleResolution.bindingForms.map((line) => "  - " + line).join("\n")
+      + "\n\nPrecedence:\n"
+      + reference.roleResolution.precedence.map((line, index) => "  " + (index + 1) + ". " + line).join("\n")
+      + "\n\nTheme groups:\n" + groups + "\n\nValid complete pair (both schemes resolved and contrast-checked):\n"
       + JSON.stringify(reference.example, null, 2) + "\n";
   }
   if (reference.referenceKind === "appearance") {
@@ -602,6 +700,7 @@ export function formatPresentationReference(reference) {
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
       + "\nLogo contrast: " + reference.logoContrastContract
+      + "\nFavicon: " + reference.faviconContract
       + "\nHeader width: " + reference.headerWidthContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary

package/src/reference-help.js

@@ -51,7 +51,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 23;
+export const REFERENCE_VERSION = 24;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 
 function deepFreeze(value) {
@@ -134,7 +134,7 @@ const DESIGN_BLUEPRINTS = deepFreeze([
         purpose: "Make a single product story legible before offering supporting choices.",
         section: { entrance: "scale", entranceStagger: "none" },
         components: [
-          { type: "image-banner", properties: { ratio: "3/1", heightMode: "viewport", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "slow-zoom" } },
+          { type: "image-banner", properties: { ratio: "3/1", heightMode: "viewport", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "parallax" } },
           { type: "cta", properties: { variant: "primary", imagePosition: "right", borderWidth: 0 } },
         ],
       },
@@ -148,7 +148,7 @@ const DESIGN_BLUEPRINTS = deepFreeze([
         ],
       },
     ],
-    motionCeiling: "Use one slow image movement or short hover response per view; never conceal names, price context, or actions behind motion.",
+    motionCeiling: "Prefer one optional image parallax per view (imageMotion: parallax-subtle or parallax). Published pages use CSS view timelines where supported and a platform-owned scroll-linked JavaScript fallback otherwise; no custom code is needed. Movement stops when scrolling stops, pauses offscreen, and is disabled for reduced motion. Without JavaScript or native timelines the image stays static. Cinematic zoom is an explicit ambient-loop alternative. Never conceal names, price context, or actions behind motion.",
     mediaBrief: "Commission or license product, material, and in-use photography; document crop-safe banner areas and supply alt text for informative images.",
     integrationBoundaries: "Use outbound links for retail, commerce, search, or booking providers. This blueprint includes none of those systems and no custom code.",
     accessibilityCautions: ["Preserve text contrast over imagery with a tested scrim and do not make text depend on hover.", "Respect reduced-motion preferences and give every campaign action a visible text label."],
@@ -374,6 +374,16 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help preview`,
     summary: "Describe authoring preview creation, waiting, and recovery.",
   }),
+  Object.freeze({
+    name: "delivery",
+    usage: `${CLI_BINARY_NAME} help delivery`,
+    summary: "Verify visitor-facing delivery after a deployment: routes, assets, runtime, browser.",
+  }),
+  Object.freeze({
+    name: "walkthrough",
+    usage: `${CLI_BINARY_NAME} help walkthrough`,
+    summary: "Design a site end to end: select, pull, edit both schemes, validate, push, review staging, promote.",
+  }),
   Object.freeze({
     name: "theme",
     usage: `${CLI_BINARY_NAME} help theme`,
@@ -397,6 +407,105 @@ export const REFERENCE_TOPICS = Object.freeze([
 ]);
 
 const WORKFLOW_REFERENCES = Object.freeze({
+  delivery: Object.freeze({
+    title: "Delivery verification",
+    summary: "delivery check reads a completed deployment's target the way a visitor does and reports HTTP delivery, runtime compatibility and (optionally) browser behaviour as separate dimensions.",
+    usage: `${CLI_BINARY_NAME} delivery check (--staging | --production [--url <origin>]) [--wait <seconds>] [--no-browser]`,
+    details: Object.freeze([
+      "A completed deployment job proves Taproot wrote what it meant to write, not that a visitor receives it. The "
+      + "check verifies the latest completed deployment for the target, and notes when the workspace recorded a "
+      + "different one.",
+      "Routes come from the workspace manifest's pages plus '/', bounded to 20; each must answer 200 text/html "
+      + "without redirecting. Internal link targets found in those pages are checked too (bounded to 40).",
+      "Assets are what the home page declares: favicon links, module preloads, the site bundle, and up to six "
+      + "images. A 200 is not enough: the content type must match the kind, so an HTML error page served as an "
+      + "image fails.",
+      "Runtime: the page's bootstrap declares the major stream, the mutable major pointer, the immutable fallback "
+      + "copy and the capability modules. The pointer's major must match, its entry must load as JavaScript, every "
+      + "declared capability must be resolvable, and a pointer behind the fallback's version is reported as a "
+      + "stale runtime pointer that returning browsers may still be on.",
+      "Browser: a fresh and a returning (same-context, cached) load are compared against the pointer's entry when "
+      + "Playwright resolves from the CLI's own install: npm install --global @taprootio/site-authoring@latest "
+      + "playwright && npx playwright install chromium, then rerun through the installed taproot-site command (a "
+      + "copy run through npx lives in npm's cache and cannot see a global Playwright). A DevTools "
+      + "session on the browser fails any document request that would leave the site origin before it is sent "
+      + "(redirect hops, frames, script-driven navigations and popups included), so a target that strays is "
+      + "reported with offOriginNavigation and is not loaded again; without that session nothing is loaded and "
+      + "the dimension is unchecked. Whether "
+      + "the returning load really reused the cached runtime entry (memory or disk) is observed through the same "
+      + "session and reported as browser.returningCache, unchecked where it cannot be observed. Every URL the "
+      + "probe reports passes the same credential withholding as redirect Locations. Without Playwright the "
+      + "dimension is reported as unchecked, never as passed; a cache-busted HTTP fetch cannot stand in for it.",
+      "Bounds: four concurrent requests, two attempts per request, 15 seconds each; --wait re-checks failures once "
+      + "after at most 120 seconds. The report stays truthful after retry exhaustion: attempts and failures are "
+      + "listed with observed and expected values and the final URL. Twenty local-only references and forty "
+      + "failure lines are kept across the whole run, and the whole report is trimmed (successful items first, "
+      + "then failed items, failure lines, local-only references, capability detail, and finally the runtime "
+      + "detail down to its verdict counts, each with totals and truncation flags) so it always fits the output bound.",
+      "Read-only and bounded: the staging cookie goes only to the staging origin, only same-origin assets and the "
+      + "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.",
+      "Verdicts: delivered (no findings), degraded (every route served and the runtime is compatible, but an asset, "
+      + "link, pointer or browser load did not match), failed (a route or the runtime did not deliver).",
+    ]),
+    example: Object.freeze({
+      command: `${CLI_BINARY_NAME} delivery check --production --url https://www.example.com/ --wait 30`,
+    }),
+  }),
+  walkthrough: Object.freeze({
+    title: "Design walkthrough",
+    summary: "One pass from selecting a site to promoting a reviewed presentation, with the reference each step relies on.",
+    usage: `${CLI_BINARY_NAME} help walkthrough`,
+    details: Object.freeze([
+      `Run the current release: npm install --global @taprootio/site-authoring, or npx --yes @taprootio/site-authoring@latest <verb>. `
+      + "Always name @latest with npx: an unversioned npx reuses whatever it cached, and Taproot accepts only the latest "
+      + "release. --version prints what is running; status reports the latest known release as cliRelease.",
+      `Select the site: ${CLI_BINARY_NAME} login, then ${CLI_BINARY_NAME} sites and ${CLI_BINARY_NAME} use <site-name-or-id>. `
+      + "sites reports each site's kind and authoring surface. A standard site takes every verb. A managed Docs site "
+      + "takes presentation only — pull, theme push, footer push, media upload, deploy, status — because its pages, "
+      + "navigation and redirects come from the Docs artifact; a prebuilt Docs site takes no verb at all.",
+      `Pull the baseline: ${CLI_BINARY_NAME} pull writes settings/taproot-styles.json with both schemes' complete effective `
+      + "themes (the stored theme resolved over the same defaults every consumer renders) beside brand.json, "
+      + "site-header.json and site-publishing-preferences.json. Keep that pull as the baseline you edit; never build "
+      + "a theme from memory or from an example. semanticMappings holds only authored pins, listed in explicitMappingTokens.",
+      "Edit both schemes: settings.lightTheme and settings.darkTheme are separate documents. Declare anchors, then roles "
+      + "(help theme lists the role slots and how anchor references resolve), tune typography per scheme, and keep "
+      + "contexts and intents paired across schemes. Set appearance scalars (default scheme, header, logos, favicon) "
+      + "in the appearance files: help appearance.",
+      "Prepare media locally: PNG, JPEG, GIF and WebP raster files only, addressed relative to the workspace root. Make "
+      + "the variants yourself with any image tool (a transparent logo, a @2x copy, 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 returned image ids so each scheme carries the artwork that reads on its header.",
+      `Validate offline: ${CLI_BINARY_NAME} validate checks the complete pair, the appearance files and the footer against `
+      + "the contracts the site enforces, and warns when a semanticMappings pin repeats the default on a token your "
+      + "roles would have moved (the pin would keep the role from rendering).",
+      `Push: ${CLI_BINARY_NAME} theme push writes the footer scheme colours, the appearance scalars, then the light and dark `
+      + "themes in that order, not atomically. A failure reports completedWrites: pull, compare the remote result "
+      + "with the workspace, reconcile, and push again. footer push owns footer prose, links and imagery.",
+      `Review on staging: ${CLI_BINARY_NAME} deploy --staging stages the presentation and returns a single-use review 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 no "
+      + "handoff could be minted, stagingPreview.reason says why and staging review mints another. 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.",
+    ]),
+    example: Object.freeze({
+      commands: Object.freeze([
+        `npx --yes @taprootio/site-authoring@latest login`,
+        `${CLI_BINARY_NAME} sites`,
+        `${CLI_BINARY_NAME} use "Riverbend Wellness"`,
+        `${CLI_BINARY_NAME} pull`,
+        `${CLI_BINARY_NAME} media upload media/logo.png media/logo-dark.png media/favicon.png`,
+        `${CLI_BINARY_NAME} validate`,
+        `${CLI_BINARY_NAME} theme push`,
+        `${CLI_BINARY_NAME} deploy --staging`,
+        `${CLI_BINARY_NAME} deploy --production`,
+      ]),
+    }),
+  }),
   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.",
@@ -511,6 +620,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
     details: Object.freeze([
       "Paths are relative to the configured workspace root, not the shell's current directory.",
       "PNG, JPEG, GIF, and WebP are accepted; retina names such as logo@2x.png and logo@3x.png are supported.",
+      "For header logos prefer genuine transparent PNG/WebP, check contrast in both themes, and include a simplified square favicon. See help appearance for branding guidance.",
+      "Prepare variants locally with any image tool before uploading: a transparent logo, its @2x copy, a scheme-specific dark logo when one asset does not read on both headers, and a square favicon. The CLI uploads what you give it; it has no recolor, crop, or SVG upload command.",
+      "Assign both schemes after uploading: lightLogoId and darkLogoId in settings/taproot-styles.json and brand.faviconId in settings/brand.json take the returned image ids; theme push writes them. See help walkthrough for the full design pass.",
       "Each result item includes media: { imageId, src, urls, width, height, alt }.",
       "The same src/urls delivery fields are saved in .taproot-site-media.json for page and component authoring.",
     ]),
@@ -538,6 +650,12 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "remain optional and old snapshots without content identity do not block deployment.",
       "deploy --staging and redirects check return a separate fresh single-use staging handoff in "
       + "stagingPreview.url, after authenticating headless redirect checks. Handoffs never go to GITHUB_OUTPUT.",
+      "On a managed Docs site deploy --staging stages settings only and still returns stagingPreview.url: open it "
+      + "once, then use the site's theme toggle to review both schemes; no page draft is needed to preview a "
+      + "presentation change. When no handoff can be minted the result carries stagingPreview.reason "
+      + "(staging.host_unavailable, staging.authority_denied, staging.surface_refused, or staging.handoff_unavailable) "
+      + "and a recovery step; run staging review to mint another (it works on every surface). Never verify a theme "
+      + "on production instead.",
       "A page path resolves through .taproot-site-manifest.json; a canonical page UUID works directly.",
       "The homepage's manifest path is empty; address it as '/', which resolves to that empty root path.",
       "Preview before approving: approve consumes the draft, so an approved page has no draft left to render and answers preview.no_draft. Review it on staging after a deploy instead.",
@@ -546,7 +664,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Success returns READY with url, snapshotId, expiresAt, storedPreviewCap, storedPreviewCount, and evictedPreviews.",
       "The url is a single-use handoff that expires two minutes after it is minted: opening it consumes it, and a reused, shared, or bookmarked URL answers Not found. Run preview page again for another.",
       "At the configured cap, creation revokes the oldest snapshot for the same page first, then the oldest snapshot held by the same key.",
-      `A stalled preview can be released with ${CLI_BINARY_NAME} preview revoke <page-id> <snapshot-id>.`,
+      `A stalled preview can be released with ${CLI_BINARY_NAME} preview revoke <page-id> <snapshot-id>. Revocation addresses the snapshot, not the draft: it works after approve has consumed the draft, revoking an already revoked snapshot succeeds again with status REVOKED, and an unknown, expired-and-cleaned-up, or other-page snapshot answers preview.not_found without revealing whether it exists elsewhere.`,
     ]),
     example: Object.freeze({ command: `${CLI_BINARY_NAME} preview page classes` }),
   }),

package/src/settings-catalog.js

@@ -2,6 +2,7 @@ import { parseTheme } from "@taprootio/espalier/shared/theme";
 
 import { SiteAuthoringError } from "./errors.js";
 import { projectFooterSettingsForWorkspace } from "./footer-contract.js";
+import { projectPulledTheme } from "./theme-projection.js";
 
 /**
  * The settings surface the authoring CLI covers.
@@ -19,7 +20,8 @@ import { projectFooterSettingsForWorkspace } from "./footer-contract.js";
  *   is not: it is gated on `site.settings.manage` rather than theme management,
  *   promotes immediately rather than through staging, and is site administration
  *   rather than authored presentation.
- * - `lightTheme` and `darkTheme` are decoded into readable JSON objects. Theme
+ * - `lightTheme` and `darkTheme` are decoded into readable JSON objects and
+ *   projected to the complete effective theme (`theme-projection.js`). Theme
  *   push validates and re-encodes them only at the wire boundary.
  * - `footerSettings` is snapshotted as its structured document. Theme push
  *   overlays only its scheme colors onto a fresh server read before using the
@@ -186,6 +188,17 @@ export function projectSettingsGroup(group, response) {
   const projected = {};
   for (const field of group.fields) {
     projected[field.name] = normalizeField(field, source[field.name]);
+    if (field.wireType === "theme") {
+      // A stored theme is what was written, possibly before a required key
+      // existed; the workspace gets the complete theme consumers actually
+      // render, resolved the way they resolve it (TR00775). The read-only
+      // provenance flag says whether Taproot's house look still layers under it.
+      projected[field.name] = projectPulledTheme(
+        projected[field.name],
+        field.name === "lightTheme" ? "light" : "dark",
+        { managedExternally: source[`${field.name}ManagedExternally`] === true },
+      );
+    }
   }
   return projected;
 }

package/src/staging-check.js

@@ -30,6 +30,10 @@ function unavailable() {
 }
 
 /** Consume only the checker's handoff; never forward a platform bearer or follow a redirect. */
+export async function authorizeStagingHandoff(client, handoff, signal) {
+  return await authorize(client, handoff, signal);
+}
+
 async function authorize(client, handoff, signal) {
   const response = await request(client, handoff.url, undefined, signal);
   const origin = new URL(handoff.stagingUrl).origin;
@@ -49,6 +53,11 @@ async function authorize(client, handoff, signal) {
   return cookie;
 }
 
+/** Withhold a Location that could reflect a staging credential; exported for the delivery check. */
+export function withholdCredentialLocation(value) {
+  return safeLocation(value);
+}
+
 function safeLocation(value) {
   if (value === null) return "";
   // The edge could be misconfigured. Never reflect handoff credentials from a