@taprootio/site-authoring 0.10.2 → 0.10.3

package/README.md

@@ -351,6 +351,10 @@ complete effective theme — the stored theme resolved over the same defaults
 every consumer renders — so a fresh workspace validates as pulled, and it
 keeps only authored `semanticMappings` pins (listed in
 `explicitMappingTokens`) because a pinned token shadows its role.
+`theme push` — and `theme push --dry-run`, which writes nothing — also runs
+Espalier's fit report over the root and every context in both schemes and
+prints each lint as a warning, such as a filled action that renders the
+opposite way round from its swatches; a lint never stops the push.
 `redirects pull` writes the site's
 redirect map to `redirects.json` with a baseline, and `redirects push`
 validates the file offline and replaces the whole map; `help redirects`

package/examples/riverbend-wellness/settings/taproot-styles.json

@@ -137,10 +137,6 @@
             "text": "anchor:reed.text",
             "hover": "anchor:reed.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:reed"
         },
         "raised": {
@@ -154,10 +150,6 @@
             "text": "anchor:reed.text",
             "hover": "anchor:reed.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:root"
         },
         "inverted": {
@@ -171,10 +163,6 @@
             "text": "anchor:ember",
             "hover": "anchor:ember.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:mist",
           "lightness": {
             "surface": 0.14,
@@ -199,7 +187,9 @@
         "series8": "#CC79A7"
       },
       "dataRamps": {},
-      "explicitMappingTokens": [],
+      "explicitMappingTokens": [
+        "actionBackground"
+      ],
       "fontBody": "\"Noto Sans\", sans-serif",
       "fontBrand": "\"Inika\", serif",
       "fontHeadings": "\"Inika\", serif",
@@ -244,7 +234,7 @@
         },
         "action": {
           "color": "anchor:ember",
-          "ink": "anchor:night"
+          "ink": "anchor:paper"
         },
         "structure": "anchor:root"
       },
@@ -256,10 +246,17 @@
         "success": 150,
         "warning": 90
       },
-      "semanticMappings": {},
+      "semanticMappings": {
+        "actionBackground": {
+          "source": "anchor:ember",
+          "lightness": "tone:ember-deep"
+        }
+      },
       "spaceRatio": 1.618,
       "stylesheets": [],
-      "tones": {},
+      "tones": {
+        "ember-deep": 0.5
+      },
       "typeRatio": 1.25,
       "variantChroma": {},
       "viewportMax": 1200,
@@ -401,10 +398,6 @@
             "text": "anchor:ember.text",
             "hover": "anchor:ember.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:reed"
         },
         "raised": {
@@ -418,10 +411,6 @@
             "text": "anchor:ember.text",
             "hover": "anchor:ember.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:reed"
         },
         "inverted": {
@@ -435,10 +424,6 @@
             "text": "anchor:reed.text",
             "hover": "anchor:reed.hover"
           },
-          "action": {
-            "color": "anchor:ember",
-            "ink": "anchor:night"
-          },
           "structure": "anchor:root",
           "lightness": {
             "surface": 0.97,
@@ -463,7 +448,9 @@
         "series8": "#CC79A7"
       },
       "dataRamps": {},
-      "explicitMappingTokens": [],
+      "explicitMappingTokens": [
+        "actionBackground"
+      ],
       "fontBody": "\"Noto Sans\", sans-serif",
       "fontBrand": "\"Inika\", serif",
       "fontHeadings": "\"Inika\", serif",
@@ -520,10 +507,17 @@
         "success": 150,
         "warning": 90
       },
-      "semanticMappings": {},
+      "semanticMappings": {
+        "actionBackground": {
+          "source": "anchor:ember",
+          "lightness": "tone:ember-light"
+        }
+      },
       "spaceRatio": 1.618,
       "stylesheets": [],
-      "tones": {},
+      "tones": {
+        "ember-light": 0.86
+      },
       "typeRatio": 1.25,
       "variantChroma": {},
       "viewportMax": 1200,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "4.17.0"
+    "@taprootio/espalier": "4.19.0"
   },
   "scripts": {
     "test": "node --test",

package/src/cli.js

@@ -300,6 +300,8 @@ const VERBS = Object.freeze([
       + "was lost is replayed safely; the site answers applied=false when it already holds the change set. "
       + "--dry-run reads the site, reports the JSON paths at which each settings file differs from it and whether "
       + "the recorded baseline is still current, and writes nothing. "
+      + "Validation includes Espalier's fit report over the root and every context in both schemes; each lint prints "
+      + "as a warning naming 'fit lint <id>' and does not stop the push, so read them in a --dry-run first. "
       + "pull writes each scheme's complete effective theme — the stored theme resolved over the same defaults every "
       + "consumer renders — so a fresh workspace validates as pulled. semanticMappings holds only authored pins, listed "
       + "in explicitMappingTokens; every other token compiles from roles at render time, so never copy default "

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.10.2";
+export const CLI_VERSION = "0.10.3";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

package/src/presentation-reference.js

@@ -42,7 +42,7 @@ import {
   MAXIMUM_THEME_OPEN_MAP_ENTRIES,
   MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS,
   REQUIRED_THEME_PROPERTIES,
-  validateAndEncodeThemePair,
+  validateAndLintThemePair,
 } from "./theme-validation.js";
 import {
   SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
@@ -90,6 +90,12 @@ function exampleTheme(defaults, scheme) {
     seedColor: scheme === "light" ? "oklch(0.58 0.14 305)" : "oklch(0.72 0.11 305)",
     pageBackgroundImage: "",
     pageBackgroundImageOpacity: 0,
+    // The shape pull writes for a theme authored through its roles: no cached
+    // mappings and a marker that claims none. The defaults' complete
+    // semanticMappings would hand every agent who copies this twenty entries
+    // the resolver never applies, each one a warning.
+    semanticMappings: {},
+    explicitMappingTokens: [],
     anchors: {
       plum: { color: "#6f2a78", text: "#4b1553", hover: "#8a3d92" },
       paper: "#fffaf4",
@@ -120,6 +126,13 @@ function exampleTheme(defaults, scheme) {
         accent: { color: "anchor:plum", text: "anchor:paper", hover: "anchor:plum.hover" },
         action: { color: "anchor:paper", ink: "anchor:midnight" },
         structure: "anchor:paper",
+        // Left to the engine, the paper action compiles to a grey button with
+        // a pale label — the wrong way round for a swatch that wants dark ink.
+        // A context declares its own action, so it needs its own pin; 0.88
+        // carries the midnight label at Lc 83 without crowding the status
+        // colours, which a paler stop does.
+        tones: { "paper-band": 0.88 },
+        semanticMappings: { actionBackground: { source: "anchor:paper", lightness: "tone:paper-band" } },
         lightness: scheme === "light"
           ? { surface: 0.16, raised1: 0.2, raised2: 0.25, raised3: 0.3, raised4: 0.36, text: 0.96, ink: 0.99 }
           : { surface: 0.12, raised1: 0.16, raised2: 0.21, raised3: 0.27, raised4: 0.34, text: 0.96, ink: 0.99 },
@@ -184,6 +197,7 @@ const THEME_GROUPS = Object.freeze([
       themeField("tones", "Open map of named 0–1 lightness values for explicit mappings.", {
         additionalProperties: true,
         maximumEntries: MAXIMUM_THEME_OPEN_MAP_ENTRIES,
+        namePattern: "lowercase slug beginning with a letter",
         maximumNameScalars: MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS,
         minimum: 0,
         maximum: 1,
@@ -288,14 +302,28 @@ export const ROLE_RESOLUTION = Object.freeze({
     + "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.",
+    "Because an anchor supplies the chroma, a near-white anchor makes a near-grey ramp. A canvas anchor around "
+    + "#FFFDF4 carries about 1% chroma, so background, every layer, and every border resolve at that 1% however "
+    + "vivid the rest of the palette is: the page reads grey and no role, lightness stop or seedColor can add the "
+    + "colour back. Give the canvas anchor the brand's own colour at full strength and let the lightness stops do "
+    + "the lightening — a violet #6136C9 canvas resolves to a pale violet background and carries about 11% chroma "
+    + "by the third layer, where a pale lavender picked to 'look like a light background' caps the whole ramp at "
+    + "its own 6%. Choose the hue before the chroma: saturating toward whichever hue holds the most chroma near "
+    + "white gives a tan page whatever the brand is, because pale yellows survive there and pale violets and blues "
+    + "do not.",
+    "A canvas anchor needs to be its own anchor. The light ink on a dark band is usually the same near-white the "
+    + "light scheme wanted for its page, so one anchor ends up serving both, and then it cannot be saturated "
+    + "without putting brand-coloured text on a brand-coloured band. Declare a second anchor for the canvas and "
+    + "leave the pale one to its ink duty.",
     "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.",
+    "A mapping in semanticMappings wins for its token only when explicitMappingTokens names it. The marker is what "
+    + "makes a mapping a pin: the resolver recompiles every token the marker leaves out, so a mapping it does not "
+    + "name is a cached value that is never applied. To pin a token, set the mapping and add the token to the "
+    + "marker; to let a role reach it, drop the token from the marker or delete the mapping. A document that "
+    + "carries no explicitMappingTokens at all predates the marker, and every mapping in it is still a pin.",
     "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.",
@@ -309,21 +337,31 @@ function themeLightness(value) {
 }
 
 /**
- * The examples must render as contrasting pairs, not merely validate: a dark
+ * Each ink is checked against the surface it is actually painted on. 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.
+ * fine and read as a defect, so the examples must render as contrasting
+ * pairs rather than merely validate. Action ink is the one that does not sit
+ * on the canvas: it is painted on the action background, and pairing it with
+ * the canvas asserts the wrong thing — an action ink chosen to read on a
+ * dark button looked like a failure once the roles reached it.
  */
+const EXAMPLE_CONTRAST_PAIRS = Object.freeze([
+  ["--esp-color-text", "--esp-color-background"],
+  ["--esp-color-headings", "--esp-color-background"],
+  ["--esp-color-link", "--esp-color-background"],
+  ["--esp-color-action-text", "--esp-color-action-background"],
+]);
+
 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"]) {
+  for (const [token, surfaceToken] of EXAMPLE_CONTRAST_PAIRS) {
+    const surface = themeLightness(properties[surfaceToken]);
     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"]}).`);
+    if (surface === undefined || lightness === undefined || Math.abs(lightness - surface) < 0.4) {
+      throw new Error(`${scheme} theme example: ${token} (${properties[token]}) does not contrast with ${surfaceToken} (${properties[surfaceToken]}).`);
     }
   }
 }
@@ -350,13 +388,17 @@ export function getThemeReference() {
     roleResolution: ROLE_RESOLUTION,
     workflow: [
       "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.",
+      "Define brand anchors first, then assign canvas, ink, accent, action, and structure roles in both schemes. Give the canvas anchor as much chroma as the design's saturation calls for: it sets the chroma of the background, every layer and every border, so a near-white paper anchor produces a grey page that no other setting can rescue.",
+      "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.",
+      "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.",
+      "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.",
       "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. 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.",
+      "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 mapping the marker does not name is never applied, so a hand-added pin needs its token added to the marker or theme push reports it as inert.",
+      "Run theme push --dry-run and clear its warnings, fit lints included; then run theme push and verify text, actions, focus states, and both schemes in authoring previews.",
     ],
     example: THEME_EXAMPLE,
   };
@@ -639,8 +681,13 @@ export function getFooterReference() {
   };
 }
 
-export function assertPresentationExamples() {
-  validateAndEncodeThemePair(THEME_EXAMPLE.lightTheme, THEME_EXAMPLE.darkTheme);
+export async function assertPresentationExamples() {
+  const themes = await validateAndLintThemePair(THEME_EXAMPLE.lightTheme, THEME_EXAMPLE.darkTheme);
+  // The example is what an agent copies, so it has to look like a finished
+  // theme: nothing for validate to warn about, fit lints included.
+  if (themes.warningCount > 0) {
+    throw new Error(`The theme example raises ${themes.warningCount} warning(s): ${themes.warnings.join(" | ")}`);
+  }
   assertExampleContrast(THEME_EXAMPLE.lightTheme, "light");
   assertExampleContrast(THEME_EXAMPLE.darkTheme, "dark");
   validateFooterDocument(FOOTER_EXAMPLE);

package/src/theme-projection.js

@@ -11,7 +11,7 @@ import {
 } from "@taprootio/espalier/shared/theme";
 
 import { SiteAuthoringError } from "./errors.js";
-import { missingThemeFields } from "./theme-validation.js";
+import { authoredMappingTokens, missingThemeFields } from "./theme-validation.js";
 
 /**
  * Project one stored scheme theme to the complete theme a consumer actually
@@ -28,16 +28,16 @@ import { missingThemeFields } from "./theme-validation.js";
  * 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.
+ * Espalier compiles them from `roles` at merge time, and since 4.18.0 the
+ * serialized `explicitMappingTokens` marker decides which stored mappings
+ * pin their token: an entry the marker does not claim is a cached value the
+ * resolver recompiles. So the projection keeps exactly the claimed mappings
+ * and drops the rest. Writing an unclaimed one back would pin a role-derived
+ * token and make the roles inert for it from then on — the failure a complete
+ * seeded theme used to exhibit for every token at once. A document carrying no
+ * usable marker predates that contract, and every mapping in it is still a
+ * pin, so all of them survive. `theme push` then stores pins only, and
+ * `theme push`'s own warnings report any mapping the marker leaves inert.
  *
  * Layering alone is not rendering parity: `mergeTheme` also lets an
  * unpinned type-role ink inherit a customized `text` mapping, and lets a
@@ -61,12 +61,6 @@ 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
@@ -97,14 +91,11 @@ export function projectPulledTheme(stored, scheme, { managedExternally = false }
   // 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 authored = authoredMappingTokens(source);
   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;
+      if (authored.has(token)) pins[token] = mapping;
     }
   }
   const projected = reconcileWithRendering(
@@ -112,6 +103,7 @@ export function projectPulledTheme(stored, scheme, { managedExternally = false }
     source,
     scheme,
     managedExternally,
+    authored,
   );
 
   requireProjectedThemeComplete(projected, scheme);
@@ -138,22 +130,18 @@ function canonicalJson(value) {
  * 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.
+ * One deliberate exception, and it is the whole point of the pins-only
+ * document: a token its author never pinned is role-derived, so writing the
+ * value it happens to resolve to today would pin it and make the roles inert
+ * for it from then on — the defect Espalier 4.18.0 fixed. Those tokens stay
+ * out of the projection and keep recompiling. Every other difference between
+ * the projection and the stored theme's rendering is written back.
  */
-function reconcileWithRendering(projected, stored, scheme, managedExternally) {
+function reconcileWithRendering(projected, stored, scheme, managedExternally, authored) {
   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.
@@ -176,11 +164,7 @@ function reconcileWithRendering(projected, stored, scheme, managedExternally) {
         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;
+          if (!authored.has(token)) continue;
           pins[token] = structuredClone(mapping);
         }
         current = { ...current, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) };

package/src/theme-validation.js

@@ -4,6 +4,7 @@ import {
   encodeTheme,
   LIGHTNESS_KEYS,
   mergeTheme,
+  parseTheme,
   SEMANTIC_COLOR_NAMES,
   validateThemePair,
 } from "@taprootio/espalier/shared/theme";
@@ -11,7 +12,10 @@ import {
 import { hasControlCharacter, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
 export const MAXIMUM_THEME_WARNINGS = 32;
-export const MAXIMUM_THEME_WARNING_SCALARS = 512;
+// Large enough for a whole fit lint: apca-target-unmet lists every pair that
+// missed its floor before the remedy, and a surface that fails across the
+// board runs past 900 scalars. Truncating it would cut the remedy off.
+export const MAXIMUM_THEME_WARNING_SCALARS = 2048;
 export const MAXIMUM_THEME_OPEN_MAP_ENTRIES = 128;
 export const MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS = 64;
 
@@ -302,46 +306,180 @@ function sameMapping(left, right) {
 }
 
 /**
- * Roles compile the semantic mappings at render time, and any mapping present
- * in `semanticMappings` pins its token over that compilation (TR00801). A pin
- * that merely repeats Espalier's default on a token the declared roles would
- * have moved is the one an author never meant: it came from a copied example
- * or a pre-projection pull, and it silently keeps the role from reaching the
- * token — the accepted-but-gray link WTFM saw. Which tokens the roles move is
- * asked of Espalier itself, by compiling the same roles with no pins at all;
- * a token the roles leave at its default, or one the marker names as a
- * deliberate pin, is never reported. It is a warning rather than a refusal
- * because the pair still renders exactly as declared; Espalier validation
- * owns the invalid cases.
+ * The tokens a stored theme's `explicitMappingTokens` marker claims, or
+ * undefined when the document has no usable marker at all.
+ *
+ * Espalier accepts a marker all-or-nothing: one entry that is not a semantic
+ * token name, one duplicate, or one name with no matching `semanticMappings`
+ * entry and it ignores the whole marker, falling back to treating every stored
+ * mapping as a pin. Reading a malformed marker leniently here — keeping the
+ * entries that happen to parse — would make this CLI describe and project a
+ * theme that renders differently from what Espalier actually resolves, which
+ * is the one thing the projection must never do.
  */
-export function shadowedRoleMappingWarnings(theme, scheme) {
-  if (!isPlainObject(theme) || !isPlainObject(theme.roles) || Object.keys(theme.roles).length === 0) return [];
-  if (!isPlainObject(theme.semanticMappings)) return [];
+export function serializedMarkerTokens(theme) {
+  const tokens = theme?.explicitMappingTokens;
+  if (!Array.isArray(tokens)) return undefined;
+  if (tokens.some((token) => typeof token !== "string" || !SEMANTIC_COLOR_NAMES.includes(token))) return undefined;
+  const unique = new Set(tokens);
+  if (unique.size !== tokens.length) return undefined;
+  if (unique.size > 0) {
+    if (!isPlainObject(theme.semanticMappings)) return undefined;
+    for (const token of unique) {
+      if (!Object.hasOwn(theme.semanticMappings, token)) return undefined;
+    }
+  }
+  return unique;
+}
+
+/**
+ * Which of a stored theme's `semanticMappings` its author actually pinned: the
+ * marker's tokens, or — for a document that carries no usable marker — all of
+ * them, since a marker-less document predates the contract and every mapping
+ * in it is still a pin.
+ */
+export function authoredMappingTokens(theme) {
+  if (!isPlainObject(theme) || !isPlainObject(theme.semanticMappings)) return new Set();
+  return serializedMarkerTokens(theme) ?? new Set(Object.keys(theme.semanticMappings));
+}
+
+/**
+ * A mapping the document carries but never claims is inert. Since Espalier
+ * 4.18.0 the serialized marker decides which `semanticMappings` entries are
+ * pins: the resolver recompiles every other token from the roles and the
+ * stored value is not applied. A cached entry that already matches what the
+ * resolver produces is invisible — that is the seeded shape every site has —
+ * so only a value the resolver will actually discard is reported. That covers
+ * both the pin that merely repeats Espalier's default on a token the roles
+ * move (the accepted-but-gray link WTFM saw, TR00801) and a mapping edited by
+ * hand without adding its token to the marker, which would otherwise vanish
+ * with no sign it was ignored. A document with no marker at all predates the
+ * contract and keeps every mapping as a pin, so it has nothing to report. It
+ * is a warning rather than a refusal because the theme still renders a valid,
+ * coherent result; Espalier validation owns the invalid cases.
+ */
+export function inertMappingWarnings(theme, scheme) {
+  if (!isPlainObject(theme) || !isPlainObject(theme.semanticMappings)) return [];
+  // No usable marker means Espalier keeps every mapping as a pin, so nothing
+  // the document carries is inert and there is nothing to report.
+  const deliberate = serializedMarkerTokens(theme);
+  if (deliberate === undefined) return [];
   const defaults = SCHEME_DEFAULTS[scheme];
-  let compiled;
+  let resolved;
   try {
-    compiled = mergeTheme(defaults, { ...theme, semanticMappings: {}, explicitMappingTokens: [] }).semanticMappings;
+    resolved = mergeTheme(defaults, theme).semanticMappings;
   } catch {
     // An invalid theme is Espalier validation's finding, not this one's.
     return [];
   }
-  const deliberate = new Set(Array.isArray(theme.explicitMappingTokens) ? theme.explicitMappingTokens : []);
   const warnings = [];
   for (const [token, mapping] of Object.entries(theme.semanticMappings)) {
     if (deliberate.has(token)) continue;
-    const fallback = defaults.semanticMappings[token];
-    if (sameMapping(mapping, fallback) && !sameMapping(compiled[token], fallback)) {
-      warnings.push(
-        `${scheme}: semanticMappings.${token} repeats the Espalier default and pins the token, so the declared roles `
-          + `never reach it; remove the pin to let the roles compile ${token}, or list it in explicitMappingTokens `
-          + `if the default is the intent.`,
-      );
+    if (sameMapping(mapping, resolved[token])) continue;
+    const applied = isPlainObject(resolved[token])
+      ? `${resolved[token].source}/${resolved[token].lightness}`
+      : "the compiled value";
+    warnings.push(
+      `${scheme}: semanticMappings.${token} is not named in explicitMappingTokens, so the resolver recompiles the `
+        + `token and this value is never applied — ${token} renders as ${applied}; list ${token} in `
+        + `explicitMappingTokens to pin the value, or remove the mapping to author the intent through the roles.`,
+    );
+  }
+  return warnings;
+}
+
+let fitReport;
+
+/**
+ * Espalier exports its fit report only from the package root, and the root
+ * re-exports every component module, which registers custom elements as it
+ * loads. This package must never do that: a process that already holds
+ * another Espalier copy — the generator's browser harness loads this package
+ * beside its own — throws on a second esp-root
+ * (generator/src/site-authoring-content-isolation.test.ts). The report itself
+ * is side-effect free and sits beside the exported theme module, so it is
+ * loaded from there, sharing that module's instance, and only when a theme is
+ * actually checked. The exact Espalier pin and this package's tests catch a
+ * release that moves it.
+ */
+function loadFitReport() {
+  fitReport ??= import(new URL("./theme-fit-report.js", import.meta.resolve("@taprootio/espalier/shared/theme")).href);
+  return fitReport;
+}
+
+/**
+ * Validation says whether Espalier accepts a theme; the fit report says how
+ * the accepted theme renders. Its lints are the findings no validator can
+ * make, because each is about the compiled result: a filled action that came
+ * out the opposite way round from its swatches (action-anchor-inversion), a
+ * text pair enforcement could not rescue (apca-target-unmet), an action lost
+ * in its canvas, or a hover weaker than its resting link. Every surface is
+ * checked — the root and each context, in both schemes — because a context
+ * declares its own action and fails on its own; a root-only check misses it.
+ * The suite's data-palette lints are left out: validateThemePair already warns
+ * about the same collisions, in the same words.
+ *
+ * The pair passed in is the encoded one that is stored, parsed back, so the
+ * report describes exactly what the published page resolves. Lints are
+ * warnings rather than refusals, matching how Espalier classifies them.
+ */
+export async function fitLintWarnings(light, dark) {
+  const { ROOT_SURFACE, themeFitReportSuite } = await loadFitReport();
+  let suite;
+  try {
+    suite = themeFitReportSuite(parseTheme(light) ?? {}, parseTheme(dark) ?? {});
+  } catch (error) {
+    // A pair that passed validation resolves, so this should not happen; if
+    // it does, say the lints were not checked rather than implying none fired.
+    return [`Espalier could not build the fit report, so no fit lints were checked: ${error?.message ?? error}`];
+  }
+  const warnings = [];
+  for (const scheme of ["light", "dark"]) {
+    for (const report of suite[scheme]) {
+      const surface = report.surface === ROOT_SURFACE ? "" : `contexts.${report.surface} `;
+      for (const lint of report.lints) {
+        warnings.push(`${scheme}: ${surface}fit lint ${lint.id} — ${lint.message}`);
+      }
     }
   }
   return warnings;
 }
 
+function boundedThemeWarnings(allWarnings) {
+  const warnings = allWarnings
+    .slice(0, MAXIMUM_THEME_WARNINGS)
+    .map((warning) =>
+      [...sanitizeDiagnostic(warning, "Theme validation warning.")]
+        .slice(0, MAXIMUM_THEME_WARNING_SCALARS)
+        .join("")
+    );
+  return {
+    warnings,
+    warningCount: allWarnings.length,
+    warningsTruncated: allWarnings.length > warnings.length,
+  };
+}
+
 export function validateAndEncodeThemePair(lightTheme, darkTheme) {
+  const { light, dark, warnings, inert } = checkThemePair(lightTheme, darkTheme);
+  return { light, dark, ...boundedThemeWarnings([...warnings, ...inert]) };
+}
+
+/**
+ * The validation `validate` and `theme push` run: everything
+ * validateAndEncodeThemePair checks, plus the fit lints over the accepted
+ * pair, bounded together so the cap and the count cover both. The lints come
+ * before the inert-mapping warnings because the seeded shape alone produces
+ * one of those per cached token and scheme — enough to fill the cap — and a
+ * lint is the finding an author can least afford to have cut off.
+ */
+export async function validateAndLintThemePair(lightTheme, darkTheme) {
+  const { light, dark, warnings, inert } = checkThemePair(lightTheme, darkTheme);
+  const lints = await fitLintWarnings(light, dark);
+  return { light, dark, ...boundedThemeWarnings([...warnings, ...lints, ...inert]) };
+}
+
+function checkThemePair(lightTheme, darkTheme) {
   requireCompleteTheme(lightTheme, "light");
   requireCompleteTheme(darkTheme, "dark");
 
@@ -372,24 +510,11 @@ export function validateAndEncodeThemePair(lightTheme, darkTheme) {
   }
   refuseAgentStylesheets(lightTheme, "light");
   refuseAgentStylesheets(darkTheme, "dark");
-  const allWarnings = [
-    ...result.warnings,
-    ...shadowedRoleMappingWarnings(lightTheme, "light"),
-    ...shadowedRoleMappingWarnings(darkTheme, "dark"),
-  ];
-  const warnings = allWarnings
-    .slice(0, MAXIMUM_THEME_WARNINGS)
-    .map((warning) =>
-      [...sanitizeDiagnostic(warning, "Theme validation warning.")]
-        .slice(0, MAXIMUM_THEME_WARNING_SCALARS)
-        .join("")
-    );
   return {
     light,
     dark,
-    warnings,
-    warningCount: allWarnings.length,
-    warningsTruncated: allWarnings.length > warnings.length,
+    warnings: result.warnings,
+    inert: [...inertMappingWarnings(lightTheme, "light"), ...inertMappingWarnings(darkTheme, "dark")],
   };
 }
 

package/src/verbs/theme-push.js

@@ -29,7 +29,7 @@ import {
   SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
-import { missingThemeFields, validateAndEncodeThemePair } from "../theme-validation.js";
+import { missingThemeFields, validateAndLintThemePair } from "../theme-validation.js";
 import { ApiError } from "../transport.js";
 import {
   readWorkspaceJson,
@@ -151,7 +151,7 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
       },
     );
   }
-  const themes = validateAndEncodeThemePair(style.lightTheme, style.darkTheme);
+  const themes = await validateAndLintThemePair(style.lightTheme, style.darkTheme);
   const scalarOperations = buildAppearanceScalarOperations(
     documents,
     knownImageIds,
@@ -316,6 +316,10 @@ export async function themePush(invocation) {
   }
   onProgress(`Validated the complete light/dark theme pair and ${scalarOperations.length} appearance settings.`);
   for (const warning of themes.warnings) onProgress(`Espalier warning: ${warning}`);
+  if (themes.warningsTruncated) {
+    const hidden = themes.warningCount - themes.warnings.length;
+    onProgress(`${hidden} more Espalier warning(s) not shown; resolve the ones above and run theme push --dry-run to see them.`);
+  }
   const warnings = {
     items: themes.warnings,
     count: themes.warningCount,

package/src/verbs/validate.js

@@ -448,6 +448,10 @@ export async function validateFixture(invocation = {}) {
     }
   }
   for (const warning of presentation.themes.warnings) onProgress(`Espalier warning: ${warning}`);
+  if (presentation.themes.warningsTruncated) {
+    const hidden = presentation.themes.warningCount - presentation.themes.warnings.length;
+    onProgress(`${hidden} more Espalier warning(s) not shown; resolve the ones above and run validate again to see them.`);
+  }
   const sharedContexts = sharedThemeContextNames(
     presentation.style.lightTheme,
     presentation.style.darkTheme,