@taprootio/site-authoring 0.6.2 → 0.7.0

package/src/cli.js

@@ -1,3 +1,4 @@
+import { CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS, CAPABILITY_DESIGN } from "./capabilities.js";
 import {
   CLI_BINARY_NAME,
   CLI_NAME,
@@ -23,6 +24,7 @@ import {
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
+  VERB_REDIRECTS_CHECK,
   VERB_REDIRECTS_PULL,
   VERB_REDIRECTS_PUSH,
   VERB_SITES,
@@ -54,11 +56,6 @@ import {
   REFERENCE_TOPICS,
   REFERENCE_VERSION,
 } from "./reference-help.js";
-import {
-  CAPABILITY_CONTENT,
-  CAPABILITY_DEPLOYMENTS,
-  CAPABILITY_DESIGN,
-} from "./capabilities.js";
 import { assertCliCurrent } from "./session.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
@@ -86,14 +83,16 @@ const VERBS = Object.freeze([
   {
     name: VERB_VALIDATE,
     tokens: ["validate"],
-    summary: "Validate a complete authoring fixture without credentials or mutation.",
+    summary: "Validate an offline fixture, or initialize one from a pulled workspace with --init.",
     positionals: "fixturePath",
     offline: true,
-    note: "Reads manifest.fixture.json plus the fixture's page, navigation, theme, appearance, header, brand, and footer files. "
+    note:
+      "Reads manifest.fixture.json plus the fixture's page, navigation, theme, appearance, header, brand, and footer files. "
       + "This proves local structure and semantics only. It does not prove authorization, live site ownership, concurrency, "
       + "persisted round trips, or rendering; run a real pull and authorized preview before deployment. "
       + `See '${CLI_BINARY_NAME} help fixture' for the manifest contract and for the path of the complete example `
-      + "fixture this package ships, which needs no credential and no pulled site.",
+      + "fixture this package ships, which needs no credential and no pulled site. "
+      + "With --init, the directory is a new destination; the current pulled workspace or --config supplies the source.",
   },
   {
     name: VERB_LOGIN,
@@ -200,7 +199,9 @@ const VERBS = Object.freeze([
       + "Markdown is deliberately one-way, so a page edited on the site since the last pull cannot be rewritten as "
       + "Markdown: pull refuses with pages.pull_conflict before changing anything under 'pages/', preserves the "
       + "site's version under '.taproot-site-state/', and leaves you to either push the local source or delete it "
-      + "and pull again. A locally edited '.pm.json' is kept rather than overwritten for the same reason.",
+      + "and pull again. A locally edited '.pm.json' is kept rather than overwritten for the same reason. "
+      + "First revisions adopted without a completed body comparison are counted in pages.revisionsRecordedWithoutBodyComparison "
+      + "and announced on the human channel. New downloads and compared bodies are excluded.",
   },
   {
     name: VERB_PAGES_PUSH,
@@ -209,7 +210,8 @@ const VERBS = Object.freeze([
     summary: "Create and update pages from the local workspace.",
     positionals: "pagePaths",
     allowRawHtml: true,
-    note: "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
+    note:
+      "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "A selected path resolves to its one authoritative source from metadata alone, and that page is then validated "
       + "exactly as a whole push would validate it — site binding, manifest integrity, live create-or-update "
@@ -236,6 +238,14 @@ const VERBS = Object.freeze([
     tokens: ["nav", "push"],
     summary: "Replace the whole navigation tree from the local workspace.",
   },
+  {
+    name: VERB_REDIRECTS_CHECK,
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
+    tokens: ["redirects", "check"],
+    summary: "Check the current redirect map through the authenticated staging edge.",
+    note: "Reports path, HTTP status and Location without following redirects. Re-run after edge propagation. "
+      + "The result includes a fresh single-use staging handoff; keep it private.",
+  },
   {
     name: VERB_REDIRECTS_PULL,
     // A redirect is a content path, and both halves of the map — read and
@@ -297,9 +307,8 @@ const VERBS = Object.freeze([
     name: VERB_DEPLOY,
     // Deployments is the only capability this verb *writes* with; the other two
     // are for reads and re-reads the server makes on its behalf (TR00691).
-    // Content: --staging builds the candidate from the live page list
-    // (DeploySiteRequest.staged_page_ids names the ids explicitly), and that
-    // list is gated on site.pages.edit_any.
+    // Content: staging redirect checks read the current redirect map;
+    // production also re-authorizes the stored candidate's pages.
     // Design: --production promotes a completed staging deployment, and the
     // pipeline re-authorizes that deployment's *stored* candidate — every
     // selected settings group and its navigation — against site.theme.manage,
@@ -340,13 +349,13 @@ const VERBS = Object.freeze([
   {
     name: VERB_STATUS,
     // Readiness and the deployment log are Deployments; the image list is
-    // Content.
+    // Content, as is the broken-reference report.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["status"],
-    summary: "Report the platform authoring switch, the CLI release, deployments, readiness, and image processing.",
-    note: "Broken references are not included: that read remains"
-      + " session-only on the server, so the result reports it as uncovered"
-      + " rather than pretending an empty list means a clean site.",
+    summary:
+      "Report the platform authoring switch, CLI release, deployments, readiness, image processing, and broken references.",
+    note: "Broken references list pages with missing image IDs or page paths in their latest editable body."
+      + " Content permission is required; a refused or failed read fails status rather than reporting a clean site.",
   },
 ]);
 
@@ -436,7 +445,8 @@ function verbHelp(verb) {
     : "";
   const targetOption = verb.target
     ? `\n  --staging        Deploy the staged site to staging.
-  --production     Promote the completed staging deployment to production.`
+  --production     Promote the completed staging deployment to production.
+  --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
     : "";
   const rawHtmlOption = verb.allowRawHtml
     ? "\n  --allow-raw-html Permit rawHtml nodes. They render verbatim and unsanitized."
@@ -466,7 +476,10 @@ function verbHelp(verb) {
     ? " It refuses only when a previous sign-in exchange recorded a newer published release than this CLI, because "
       + "Taproot accepts only the latest; with nothing recorded it runs."
     : "";
-  const boundary = selfContained
+  const boundary = verb.name === VERB_VALIDATE
+    ? "Validation uses no credential, configuration, network or write. With --init it reads the pulled workspace "
+      + `or selected configuration and writes a new fixture directory, still without credentials or network.${upgradeGate}`
+    : selfContained
     ? "This offline verb uses no credential and reads no configuration, and performs no network request and no "
       + `write.${upgradeGate}`
     : verb.offline
@@ -478,7 +491,14 @@ function verbHelp(verb) {
       + `existing automation unaffected by login and logout.`
     : `The site-scoped credential is taken from ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} when it is set, and otherwise `
       + `from the credential '${CLI_BINARY_NAME} ${VERB_LOGIN}' stores outside the repository.`;
-  const options = selfContained
+  const options = verb.name === VERB_VALIDATE
+    ? `Options:
+  --init           Export a pulled workspace into the new fixture directory.
+  --config <path>  Before the verb; source configuration for --init only.
+  --quiet          Suppress human progress. The JSON result is unchanged.
+  --help           Show this help.
+  --version        Show the package version.`
+    : selfContained
     ? `Options:
   --quiet          Suppress human progress. The JSON result is unchanged.
   --help           Show this help.
@@ -561,7 +581,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "fixture"
       || topic === "redirects"
     )
-    && (subject !== undefined || extra.length > 0)) {
+    && (subject !== undefined || extra.length > 0)
+  ) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
   }
   if ((topic === "page" || topic === "component") && (subject === undefined || extra.length > 0)) {
@@ -613,7 +634,12 @@ function referenceResult(parsed) {
     case "media":
     case "preview":
     case "fixture":
-      return { ...result, topic: "workflow", referenceKind: parsed.topic, reference: getWorkflowReference(parsed.topic) };
+      return {
+        ...result,
+        topic: "workflow",
+        referenceKind: parsed.topic,
+        reference: getWorkflowReference(parsed.topic),
+      };
     case "theme":
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
     case "appearance":
@@ -699,7 +725,10 @@ function parseArguments(arguments_) {
   // origin the sign-in belongs to — so they accept it. whoami is offline and
   // reads both the store and the configuration, so it accepts it too: the test
   // is "reads nothing local", not "makes no request".
-  if (verb.offline && !verb.readsLocalState && configPath !== undefined) {
+  if (
+    verb.offline && !verb.readsLocalState && configPath !== undefined
+    && !(verb.name === VERB_VALIDATE && rest.includes("--init"))
+  ) {
     throw usageError("cli.config_option", "--config applies only to verbs that read the site configuration.", {
       field: "configPath",
     });
@@ -707,14 +736,21 @@ function parseArguments(arguments_) {
   if (rest.length === 1 && rest[0] === "--help") return { mode: "verb_help", verb };
   if (rest.length === 1 && rest[0] === "--version") return { mode: "version" };
 
+  let init = false;
   let quiet = false;
   let deployTarget;
+  let allowFailedPreview = false;
   let allowRawHtml = false;
   let json = false;
   let keyName;
   const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
+    if (verb.name === VERB_VALIDATE && argument === "--init") {
+      if (init) throw usageError("cli.duplicate_option", "--init may be supplied only once.");
+      init = true;
+      continue;
+    }
     if (argument === "--quiet") {
       if (quiet) throw usageError("cli.duplicate_option", "--quiet may be supplied only once.");
       quiet = true;
@@ -739,6 +775,13 @@ function parseArguments(arguments_) {
       deployTarget = candidate;
       continue;
     }
+    if (verb.target && argument === "--allow-failed-preview") {
+      if (allowFailedPreview) {
+        throw usageError("cli.duplicate_option", "--allow-failed-preview may be supplied only once.");
+      }
+      allowFailedPreview = true;
+      continue;
+    }
     if (verb.allowRawHtml && argument === "--allow-raw-html") {
       if (allowRawHtml) {
         throw usageError("cli.duplicate_option", "--allow-raw-html may be supplied only once.");
@@ -852,8 +895,8 @@ function parseArguments(arguments_) {
     // the server resolves for them, not only the ones the verb's writes name.
     // It reaches the exchange so a content push never holds deploy, and a pull
     // never holds delete (TR00645). Two things count beyond the writes
-    // (TR00691): a read (nav push and deploy each list the site's pages first,
-    // and that list is gated on a Content permission), and a re-authorization
+    // (TR00691): reads (nav push lists pages; deploy checks the redirect map),
+    // each gated on Content, and re-authorization
     // of server-held state (deploy --production re-checks the promoted
     // candidate's stored settings and navigation against a Design permission).
     // `VERB_CAPABILITIES` below is what the tests pin against the routes each
@@ -862,6 +905,8 @@ function parseArguments(arguments_) {
     configPath,
     quiet,
     deployTarget,
+    allowFailedPreview,
+    init,
     allowRawHtml,
     keyName,
     positionals: verb.positionals
@@ -936,6 +981,8 @@ export async function runCli({
       environment,
       configPath: parsed.configPath,
       deployTarget: parsed.deployTarget,
+      allowFailedPreview: parsed.allowFailedPreview,
+      init: parsed.init,
       quiet: parsed.quiet,
       allowRawHtml: parsed.allowRawHtml,
       keyName: parsed.keyName,

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.6.2";
+export const CLI_VERSION = "0.7.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -82,6 +82,7 @@ export const VERB_LOGIN = "login";
 export const VERB_LOGOUT = "logout";
 export const VERB_PAGES_PUSH = "pages push";
 export const VERB_NAV_PUSH = "nav push";
+export const VERB_REDIRECTS_CHECK = "redirects check";
 export const VERB_REDIRECTS_PULL = "redirects pull";
 export const VERB_REDIRECTS_PUSH = "redirects push";
 export const VERB_THEME_PUSH = "theme push";

package/src/content/components.js

@@ -61,7 +61,6 @@ const list = (item) => Object.freeze({ kind: "array", item });
 const shape = (fields, options = {}) => Object.freeze({ kind: "object", fields: Object.freeze(fields), ...options });
 const image = () => Object.freeze({ kind: "image" });
 const safeUrl = (options = {}) => Object.freeze({ kind: "safe-url", ...options });
-const actionUrl = () => Object.freeze({ kind: "action-url" });
 const textureName = () => Object.freeze({ kind: "texture-name", maximumLength: 64 });
 const withOmission = (spec, whenOmitted) => Object.freeze({ ...spec, whenOmitted: Object.freeze(whenOmitted) });
 
@@ -149,7 +148,7 @@ const CTA = Object.freeze({
   heading: str(),
   description: str(),
   buttonText: str(),
-  buttonUrl: actionUrl(),
+  buttonUrl: safeUrl(),
   variant: enumOf("primary", "danger"),
   borderWidth: num({
     integer: true,
@@ -534,15 +533,9 @@ function referenceSchema(spec) {
       return {
         type: "string",
         format: spec.allowEmpty === false ? "safe-url" : "safe-url-or-empty",
-        description:
-          `${spec.allowEmpty === false ? "An" : "Empty, or an"} explicit HTTP(S), mailto, or tel URL; a root-relative path that does not begin with //; a fragment; a query; or a relative URL. Backslashes and ASCII control characters are rejected.`,
-      };
-    case "action-url":
-      return {
-        type: "string",
-        format: "action-url-or-empty",
-        description:
-          "Empty, an explicit HTTP(S) URL, or a root-relative path that does not begin with //. Backslashes and ASCII control characters are rejected.",
+        description: `${
+          spec.allowEmpty === false ? "An" : "Empty, or an"
+        } explicit HTTP(S), mailto, or tel URL; a root-relative path that does not begin with //; a fragment; a query; or a relative URL. Backslashes and ASCII control characters are rejected. Contact URLs require a non-empty body and refuse tel:// and mailto:// authority forms.`,
       };
     case "texture-name":
       return {
@@ -645,9 +638,9 @@ function describe(spec) {
     case "uuid":
       return "a canonical lowercase UUID";
     case "safe-url":
-      return `${spec.allowEmpty === false ? "a" : "an empty string or a"} safe HTTP(S), mailto, tel, non-protocol-relative root path, fragment, query, or relative URL; backslashes and ASCII control characters are rejected`;
-    case "action-url":
-      return "an empty string, explicit HTTP(S) URL, or non-protocol-relative root path; backslashes and ASCII control characters are rejected";
+      return `${
+        spec.allowEmpty === false ? "a" : "an empty string or a"
+      } safe HTTP(S), mailto, tel, non-protocol-relative root path, fragment, query, or relative URL; backslashes and ASCII control characters are rejected`;
     case "texture-name":
       return "a lowercase hyphenated texture identifier of at most 64 characters";
     default:
@@ -682,25 +675,6 @@ function validateValue(spec, value, path, errors) {
         fail(describe(spec));
       }
       return;
-    case "action-url": {
-      if (typeof value !== "string") {
-        fail(describe(spec));
-        return;
-      }
-      const trimmed = value.trim();
-      const lower = trimmed.toLowerCase();
-      if (
-        value !== ""
-        && (trimmed === ""
-          || value.includes("\\")
-          || hasAsciiControl(value)
-          || trimmed.startsWith("//")
-          || (!trimmed.startsWith("/") && !lower.startsWith("http://") && !lower.startsWith("https://")))
-      ) {
-        fail(describe(spec));
-      }
-      return;
-    }
     case "texture-name":
       if (
         typeof value !== "string"

package/src/content/free-form-section-registry.json

@@ -384,7 +384,8 @@
             "required": true,
             "minScalars": 1,
             "maxScalars": 120,
-            "nonWhitespace": true
+            "nonWhitespace": true,
+            "pattern": "^(?![\\s\\S]*<[bB][rR]\\s*/?>)[^\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f-\\u009f\\u2028\\u2029\\ufeff]*$"
           },
           "label": {
             "type": "plain-text",
@@ -392,7 +393,8 @@
             "default": null,
             "minScalars": 1,
             "maxScalars": 120,
-            "nonWhitespace": true
+            "nonWhitespace": true,
+            "pattern": "^(?![\\s\\S]*<[bB][rR]\\s*/?>)[^\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f-\\u009f\\u2028\\u2029\\ufeff]*$"
           },
           "url": {
             "type": "safe-url",

package/src/content/inline-facts.js

@@ -79,6 +79,12 @@ export function normalizeInlineFactsItems(
           CODES.attrInvalid,
           `Inline fact ${name} must contain at most ${field.maxScalars} Unicode scalar values.`,
         );
+      } else if (!new RegExp(field.pattern, "u").test(entry)) {
+        report(
+          `${itemPath}/${name}`,
+          CODES.attrInvalid,
+          `Inline fact ${name} allows Unicode spaces, tabs, and LF/CRLF line breaks; other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal <br> tags are not supported.`,
+        );
       }
     }
 

package/src/content/tiptap-prosemirror.ts

@@ -52,6 +52,7 @@ export interface RenderProseMirrorOptions {
   freeFormSections?: boolean;
   imageDefaults?: {
     placement?: TiptapImagePresentationPlacement | string | null;
+    /** The page shell emits this default once so rich-text formats inherit it. */
     maxHeightVh?: TiptapImageMaxHeightVh | number | null;
   };
 }
@@ -503,8 +504,7 @@ type NormalizedInlineFact = {
 /**
  * The row is a list, not a description list: a fact whose value names itself
  * carries no label, and `dl` has no valid shape for a `dd` without a `dt`.
- * The label keeps its leading source position so the CSS `order` rules that
- * lift the value above it stay unchanged for a labelled fact. The list roles
+ * Source order matches the visual order: value, then label. The list roles
  * are explicit because `list-style: none` makes WebKit drop them, and the
  * label is separated from the value by a space: search indexers take adjacent
  * inline elements as one word, and a whitespace-only anonymous flex item is
@@ -524,11 +524,11 @@ function renderInlineFacts(
       : escapeHtml(fact.value);
     const label = fact.label === undefined
       ? ""
-      : `${renderElement("span", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))} `;
+      : ` ${renderElement("span", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))}`;
     return renderElement(
       "li",
       { class: "taproot-inline-fact", role: "listitem" },
-      `${label}${renderElement("span", { class: "taproot-inline-fact__value" }, value)}`,
+      `${renderElement("span", { class: "taproot-inline-fact__value" }, value)}${label}`,
     );
   }).join("");
   return renderElement(
@@ -1013,7 +1013,7 @@ function resolveImagePresentation(
   attrs: Record<string, JsonValue | undefined>,
   defaults: RenderProseMirrorOptions["imageDefaults"],
 ): Record<string, string | number | undefined> {
-  const maxHeight = resolveMaxHeight(attrs.maxHeightVh, defaults?.maxHeightVh);
+  const explicitMaxHeight = explicitImageMaxHeight(attrs.maxHeightVh);
   const maxHeightOverride = normalizeCssLengthOverride(attrs.maxHeight, { allowNone: true });
   const borderWidthOverride = normalizeCssLengthOverride(attrs.borderWidth);
   const placement = resolvePlacement(attrs, defaults?.placement);
@@ -1022,9 +1022,12 @@ function resolveImagePresentation(
   if (maxHeightOverride) styleParts.push(`--taproot-article-image-max-height: ${maxHeightOverride}`);
   if (borderWidthOverride) styleParts.push(`--esp-image-border: ${imageBorderValue(borderWidthOverride)}`);
   return {
+    // The page shell owns the inherited site default so HTML and structured
+    // rich text share it. Serialize only an explicit legacy choice; this
+    // includes 60vh when it intentionally overrides a taller site default.
     // An explicit CSS max height supersedes the legacy vh enum entirely.
-    ...(maxHeightOverride === null && maxHeight !== DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH
-      ? { "data-image-max-height-vh": maxHeight }
+    ...(maxHeightOverride === null && explicitMaxHeight !== null
+      ? { "data-image-max-height-vh": explicitMaxHeight }
       : {}),
     ...(maxHeightOverride ? { "data-image-max-height": maxHeightOverride } : {}),
     ...(borderWidthOverride ? { "data-image-border-width": borderWidthOverride } : {}),
@@ -1034,11 +1037,9 @@ function resolveImagePresentation(
   };
 }
 
-function resolveMaxHeight(value: unknown, defaultValue: unknown): TiptapImageMaxHeightVh {
-  if (value === TIPTAP_SITE_DEFAULT || value === undefined || value === null) {
-    return normalizeImageMaxHeight(defaultValue);
-  }
-  return normalizeImageMaxHeight(value);
+function explicitImageMaxHeight(value: unknown): TiptapImageMaxHeightVh | null {
+  if (value === TIPTAP_SITE_DEFAULT || value === undefined || value === null) return null;
+  return isImageMaxHeightOption(value) ? imageMaxHeightOption(value) : null;
 }
 
 function resolvePlacement(
@@ -1068,10 +1069,15 @@ function isAbsentPresentationValue(value: unknown): boolean {
 }
 
 export function normalizeImageMaxHeight(value: unknown): TiptapImageMaxHeightVh {
-  const parsed = typeof value === "number" ? value : Number(value);
-  return TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS.includes(parsed as TiptapImageMaxHeightVh)
-    ? parsed as TiptapImageMaxHeightVh
-    : DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH;
+  return isImageMaxHeightOption(value) ? imageMaxHeightOption(value) : DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH;
+}
+
+function isImageMaxHeightOption(value: unknown): boolean {
+  return TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS.includes(imageMaxHeightOption(value));
+}
+
+function imageMaxHeightOption(value: unknown): TiptapImageMaxHeightVh {
+  return (typeof value === "number" ? value : Number(value)) as TiptapImageMaxHeightVh;
 }
 
 const CSS_LENGTH_UNITS = "px|em|rem|ch|ex|vw|vh|svh|lvh|dvh|svw|lvw|dvw|vmin|vmax|%";

package/src/content/vocabulary.js

@@ -1,3 +1,4 @@
+import { isContactOrWebUrl } from "../contact-url.js";
 import { sanitizeDiagnostic } from "../errors.js";
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
 
@@ -17,10 +18,12 @@ import freeFormSectionRegistry from "./free-form-section-registry.json" with { t
  * page that publishes successfully and renders wrong, so this package rejects
  * them before they are sent.
  *
- * The rule for the reimplementations below: match the renderer exactly,
+ * The rule for the reimplementations below: match the renderer,
  * including the parts that look like bugs. A "safer" copy would reject
  * documents the renderer accepts, or accept documents it silently mangles,
- * and either way the CLI would stop being the schema.
+ * and either way the CLI would stop being the schema. The explicit TR00743
+ * compatibility exception is contact URLs: new authoring refuses malformed
+ * authority forms while the renderer preserves previously stored links.
  */
 
 // ---------------------------------------------------------------------------
@@ -227,6 +230,7 @@ export function isSafeUrl(url) {
 
   try {
     const parsed = new URL(cleaned);
+    if (["mailto:", "tel:"].includes(parsed.protocol)) return isContactOrWebUrl(cleaned);
     return ["http:", "https:", "mailto:", "tel:"].includes(parsed.protocol);
   } catch {
     return true;

package/src/errors.js

@@ -54,6 +54,21 @@ export function normalizePreviewRecovery(preview) {
   });
 }
 
+/** No renderer messages or content: only stable typed diagnostic tokens. */
+export function normalizePreviewDiagnostic(value) {
+  if (
+    !value || typeof value !== "object" || !isCanonicalUuid(value.pageId)
+    || typeof value.errorClass !== "string" || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/u.test(value.errorClass)
+  ) return undefined;
+  const result = { errorClass: value.errorClass, pageId: value.pageId };
+  for (const field of ["nodeType", "attribute"]) {
+    if (value[field] === undefined || value[field] === "") continue;
+    if (typeof value[field] !== "string" || !/^[a-z][a-zA-Z0-9_-]{0,127}$/u.test(value[field])) return undefined;
+    result[field] = value[field];
+  }
+  return result;
+}
+
 function isUnsafeDiagnosticCodePoint(codePoint) {
   return codePoint <= 0x1f
     || (codePoint >= DELETE_CODE_POINT && codePoint <= C1_LAST_CODE_POINT)
@@ -88,6 +103,18 @@ export class SiteAuthoringError extends Error {
     this.code = typeof code === "string" && /^[a-z0-9_.-]+$/u.test(code)
       ? code
       : "site.failed";
+    this.details = Array.isArray(options.details)
+      ? options.details.slice(0, 256).filter((item) =>
+        item?.code === "theme.setting_missing"
+        && typeof item.field === "string" && typeof item.message === "string"
+      )
+        .map((item) => ({
+          code: item.code,
+          field: sanitizeDiagnostic(item.field, "").slice(0, 200),
+          message: "is missing (added in a later contract; run taproot-site pull)",
+        }))
+      : undefined;
+    this.previewDiagnostic = normalizePreviewDiagnostic(options.previewDiagnostic);
     this.field = typeof options.field === "string" ? sanitizeDiagnostic(options.field, "") : undefined;
     this.status = typeof options.status === "string" ? sanitizeDiagnostic(options.status, "") : undefined;
     this.alternatives = Array.isArray(options.alternatives)

package/src/fixture-contract.js

@@ -29,11 +29,11 @@ export const FIXTURE_REQUIRED_ROOT_FIELDS = Object.freeze([
 ]);
 
 /**
- * Root fields `pull` writes that a fixture may carry unchanged. They are
- * accepted and read for nothing: a fixture proves local structure, and neither
- * the snapshot time nor a recorded deployment can be checked without a server.
+ * Optional pull metadata. Snapshot time and deployment receipts are not live
+ * evidence. When appearance/footer are present, validate checks their local
+ * image bindings and footer hashes against the fixture settings.
  */
-export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments"]);
+export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments", "appearance", "footer"]);
 
 /** Every root field the manifest may declare. Anything else is refused. */
 export const FIXTURE_ROOT_FIELDS = Object.freeze(