@taprootio/site-authoring 0.8.4 → 0.8.6

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,
@@ -541,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);
 }
 
@@ -600,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") {

package/src/reference-help.js

@@ -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.",
@@ -512,6 +621,8 @@ const WORKFLOW_REFERENCES = 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.",
     ]),
@@ -539,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.",
@@ -547,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

package/src/theme-projection.js

@@ -0,0 +1,213 @@
+import {
+  buildTaprootDarkTheme,
+  buildTaprootLightTheme,
+  DEFAULT_DARK_THEME,
+  DEFAULT_LIGHT_THEME,
+  encodeTheme,
+  layerThemes,
+  mergePartials,
+  mergeTheme,
+  parseTheme,
+} from "@taprootio/espalier/shared/theme";
+
+import { SiteAuthoringError } from "./errors.js";
+import { missingThemeFields } from "./theme-validation.js";
+
+/**
+ * Project one stored scheme theme to the complete theme a consumer actually
+ * renders (TR00775).
+ *
+ * Taproot stores what was written. A site whose theme was seeded or written
+ * before a key existed keeps a sparse document, and every consumer — the
+ * app's preview, the generator, the published runtime — resolves it by
+ * layering the same defaults underneath: Espalier's scheme defaults plus,
+ * for a theme Taproot still manages, the Taproot house theme with an empty
+ * page background. A theme the CLI manages (`*ThemeManagedExternally`) is
+ * rendered as stored over Espalier's defaults alone. `pull` writes exactly
+ * that effective theme, so a fresh workspace validates and a designer edits
+ * every group with its authoritative value instead of reconstructing it.
+ *
+ * Semantic mappings are the one group that is *not* filled from defaults.
+ * Espalier compiles them from `roles` at merge time; a mapping stored in
+ * `semanticMappings` pins that token and shadows whatever the roles would
+ * have produced. Copying the defaults' twenty-three mappings into the
+ * document would therefore freeze them and make later role changes inert
+ * — the failure a complete seeded theme already exhibits. The projection
+ * keeps only the mappings that are authored pins: those the stored marker
+ * names, plus any mapping whose value differs from the effective default
+ * (a pin added by hand without updating the marker). It writes the marker
+ * for exactly that set, so `theme push` stores pins only and roles compile
+ * for everything else.
+ *
+ * Layering alone is not rendering parity: `mergeTheme` also lets an
+ * unpinned type-role ink inherit a customized `text` mapping, and lets a
+ * `chroma.text` override flow into the type-role chroma bands the document
+ * did not set. Filling those groups from the defaults, or dropping a
+ * cached mapping that was holding a token at its default, would change
+ * what the site renders. So the projection is reconciled against Espalier
+ * itself: the stored theme is resolved exactly the way its consumers resolve
+ * it, the projected document is resolved the same way, and every difference
+ * is written back as the rendered value (a mapping pin, a chroma band). The
+ * result validates, keeps the author's pins, and renders what the site
+ * rendered before the pull.
+ */
+
+const SCHEME_DEFAULTS = Object.freeze({
+  light: { defaults: DEFAULT_LIGHT_THEME, house: buildTaprootLightTheme },
+  dark: { defaults: DEFAULT_DARK_THEME, house: buildTaprootDarkTheme },
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sameMapping(left, right) {
+  return isPlainObject(left) && isPlainObject(right)
+    && left.source === right.source && left.lightness === right.lightness
+    && Object.keys(left).length === Object.keys(right).length;
+}
+
+/**
+ * The complete theme a consumer layers a stored theme onto: Espalier's
+ * scheme defaults, and — unless the theme is managed externally — the
+ * Taproot house theme with the empty page background both the BFF and the
+ * generator clear before rendering.
+ */
+export function effectiveThemeBase(scheme, { managedExternally = false } = {}) {
+  const { defaults, house } = SCHEME_DEFAULTS[scheme];
+  const houseTheme = parseTheme(house("")) ?? {};
+  if (managedExternally) {
+    // Espalier's defaults carry no page background at all; the stored
+    // contract requires both keys. No image is the rendered truth, and the
+    // opacity of an absent image is neutral, so the house value fills it.
+    return {
+      ...defaults,
+      pageBackgroundImage: "",
+      pageBackgroundImageOpacity: houseTheme.pageBackgroundImageOpacity,
+    };
+  }
+  return { ...mergePartials(defaults, houseTheme), pageBackgroundImage: "" };
+}
+
+export function projectPulledTheme(stored, scheme, { managedExternally = false } = {}) {
+  const source = isPlainObject(stored) ? stored : {};
+  const base = effectiveThemeBase(scheme, { managedExternally });
+  const { semanticMappings: _baseMappings, ...layerable } = base;
+  // The marker is set on the base so mergePartials treats every stored
+  // mapping as authored; the pin filter below then decides which survive.
+  const merged = mergePartials({ ...layerable, semanticMappings: {}, explicitMappingTokens: [] }, source);
+
+  const marker = Array.isArray(source.explicitMappingTokens)
+    ? new Set(source.explicitMappingTokens.filter((token) => typeof token === "string"))
+    : undefined;
+  const pins = {};
+  if (isPlainObject(source.semanticMappings)) {
+    for (const [token, mapping] of Object.entries(source.semanticMappings)) {
+      const cachedDefault = sameMapping(mapping, base.semanticMappings?.[token]);
+      if (marker?.has(token) || !cachedDefault) pins[token] = mapping;
+    }
+  }
+  const projected = reconcileWithRendering(
+    { ...merged, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) },
+    source,
+    scheme,
+    managedExternally,
+  );
+
+  requireProjectedThemeComplete(projected, scheme);
+  return projected;
+}
+
+/** What a consumer renders for a stored theme: the partial it layers, resolved over Espalier's defaults. */
+function renderedTheme(stored, scheme, managedExternally) {
+  const { defaults, house } = SCHEME_DEFAULTS[scheme];
+  const layered = managedExternally
+    ? layerThemes(encodeTheme(stored))
+    : layerThemes(house(""), encodeTheme({ pageBackgroundImage: "" }), encodeTheme(stored));
+  return mergeTheme(defaults, parseTheme(layered) ?? {});
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return JSON.stringify(value.map((entry) => JSON.parse(canonicalJson(entry))));
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  return JSON.stringify(Object.fromEntries(Object.keys(value).sort().map((key) => [key, JSON.parse(canonicalJson(value[key]))])));
+}
+
+/**
+ * Bring the projected document to rendering parity with the stored theme.
+ * Two passes suffice: a mapping pin can change what a companion token
+ * inherits, so the comparison runs again after the first corrections.
+ *
+ * One deliberate exception: a cached default mapping on a token the stored
+ * theme's own roles would move is the shadowing pin TR00801 documents and
+ * warns about. Restoring it would keep the roles inert, so it stays dropped
+ * and the role-compiled value is accepted as the rendering the author asked
+ * for. Every other difference is written back.
+ */
+function reconcileWithRendering(projected, stored, scheme, managedExternally) {
+  const { defaults } = SCHEME_DEFAULTS[scheme];
+  let rendered;
+  let roleCompiled;
+  try {
+    rendered = renderedTheme(stored, scheme, managedExternally);
+    const declaresRoles = isPlainObject(stored.roles) && Object.keys(stored.roles).length > 0;
+    roleCompiled = declaresRoles
+      ? mergeTheme(defaults, { ...stored, semanticMappings: {}, explicitMappingTokens: [] }).semanticMappings
+      : undefined;
+  } catch {
+    // An invalid stored theme cannot be rendered for comparison; validation
+    // reports it, and the layered projection is the best available document.
+    return projected;
+  }
+  let current = projected;
+  for (let pass = 0; pass < 2; pass += 1) {
+    let candidate;
+    try {
+      candidate = mergeTheme(defaults, current);
+    } catch {
+      return current;
+    }
+    let changed = false;
+    for (const key of Object.keys(rendered)) {
+      if (key === "explicitMappingTokens") continue;
+      if (canonicalJson(rendered[key]) === canonicalJson(candidate[key])) continue;
+      changed = true;
+      if (key === "semanticMappings") {
+        const pins = { ...current.semanticMappings };
+        for (const [token, mapping] of Object.entries(rendered.semanticMappings)) {
+          if (canonicalJson(mapping) === canonicalJson(candidate.semanticMappings[token])) continue;
+          const storedMapping = isPlainObject(stored.semanticMappings) ? stored.semanticMappings[token] : undefined;
+          const cachedDefaultTheRolesMove = roleCompiled !== undefined
+            && sameMapping(storedMapping, defaults.semanticMappings[token])
+            && canonicalJson(candidate.semanticMappings[token]) === canonicalJson(roleCompiled[token]);
+          if (cachedDefaultTheRolesMove) continue;
+          pins[token] = structuredClone(mapping);
+        }
+        current = { ...current, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) };
+      } else {
+        current = { ...current, [key]: structuredClone(rendered[key]) };
+      }
+    }
+    if (!changed) break;
+  }
+  return current;
+}
+
+/**
+ * The refusal for a projection that still lacks required fields. Reachable
+ * only when Espalier's defaults and the server response together omit a key
+ * this CLI requires — a contract drift between releases, never a stale
+ * workspace — so the remedy is a report, not another pull. Exported so the
+ * refusal itself is testable without an incomplete default to hand.
+ */
+export function requireProjectedThemeComplete(projected, scheme) {
+  const missing = missingThemeFields(projected, scheme);
+  if (missing.length === 0) return;
+  throw new SiteAuthoringError(
+    "theme.projection_incomplete",
+    "Taproot's settings response and the Espalier defaults this CLI ships still omit required theme fields. "
+      + "This is a contract problem between the server projection and this CLI release, not a stale workspace: "
+      + "repeating taproot-site pull cannot supply them. Report the listed paths with the CLI and server versions.",
+    { field: missing[0], alternatives: missing },
+  );
+}