@taprootio/site-authoring 0.1.1 → 0.3.0

package/src/footer-contract.js

@@ -1,3 +1,8 @@
+import {
+  CONTACT_OR_WEB_URL_MAX_LENGTH,
+  CONTACT_OR_WEB_URL_REQUIREMENT,
+  isContactOrWebUrl,
+} from "./contact-url.js";
 import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { FOOTER_COLOR_TOKENS, requireAppearanceColor } from "./theme-validation.js";
 
@@ -15,7 +20,7 @@ export const FOOTER_LIMITS = Object.freeze({
   linkLabelLength: 120,
   bottomTextLength: 500,
   featureImageAltLength: 300,
-  externalUrlLength: 2_048,
+  externalUrlLength: CONTACT_OR_WEB_URL_MAX_LENGTH,
   backgroundRepeatHeightMinimum: 64,
   backgroundRepeatHeightMaximum: 512,
   backgroundRepeatHeightStep: 16,
@@ -198,33 +203,17 @@ function stableId(value, path, seen, label) {
   return value;
 }
 
+// A `tel:` or `mailto:` target is returned exactly as authored: the number's
+// punctuation and the address's plus-tag are content, and `URL.toString()`
+// re-encodes both. Only the whitespace the server would strip is removed.
 function safeExternalUrl(value, path, tolerateStoredValues) {
   if (typeof value !== "string") {
-    fail("footer.url_invalid", `${path} must be a bounded absolute http or https URL.`, path);
+    fail("footer.url_invalid", `${path} ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, path);
   }
   const normalized = trimLikeServer(value);
   if (tolerateStoredValues) return normalized;
-  if (
-    normalized.length === 0
-    || normalized.length > FOOTER_LIMITS.externalUrlLength
-    || hasControlCharacter(normalized)
-    || normalized.includes("\\")
-  ) {
-    fail("footer.url_invalid", `${path} must be a bounded absolute http or https URL.`, path);
-  }
-  let parsed;
-  try {
-    parsed = new URL(normalized);
-  } catch {
-    fail("footer.url_invalid", `${path} must be an absolute http or https URL.`, path);
-  }
-  if (
-    (parsed.protocol !== "http:" && parsed.protocol !== "https:")
-    || parsed.username !== ""
-    || parsed.password !== ""
-    || parsed.hostname === ""
-  ) {
-    fail("footer.url_invalid", `${path} must use http or https without embedded credentials.`, path);
+  if (!isContactOrWebUrl(normalized, FOOTER_LIMITS.externalUrlLength)) {
+    fail("footer.url_invalid", `${path} ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, path);
   }
   return normalized;
 }
@@ -618,16 +607,25 @@ export function footerImageIds(value) {
 export const FOOTER_EXAMPLE = Object.freeze({
   enabled: true,
   showBrand: true,
+  // The aside CTA is where a local business puts the thing a visitor came for.
+  // A phone number is a `tel:` target, emitted verbatim so it stays dialable.
   asideCta: Object.freeze({
     id: "103e726d-3152-49c8-bf14-c947b1bd8a14",
-    label: "Talk with us",
-    externalUrl: "https://example.com/contact",
+    label: "Call the studio",
+    externalUrl: "tel:+15555550123",
   }),
-  bottomLinks: Object.freeze([Object.freeze({
-    id: "28363e08-b341-42fc-bc83-8dd73fa87904",
-    label: "Privacy",
-    externalUrl: "https://example.com/privacy",
-  })]),
+  bottomLinks: Object.freeze([
+    Object.freeze({
+      id: "28363e08-b341-42fc-bc83-8dd73fa87904",
+      label: "Privacy",
+      externalUrl: "https://example.com/privacy",
+    }),
+    Object.freeze({
+      id: "9e2d1f04-4bb0-4a2d-9d1a-6d3b0d0a4c77",
+      label: "Email us",
+      externalUrl: "mailto:hello@example.com",
+    }),
+  ]),
   light: Object.freeze({
     backgroundColor: "--esp-color-layer-1",
     textColor: "--esp-color-text",

package/src/presentation-reference.js

@@ -57,6 +57,12 @@ function getEspalierVersion() {
 
 const OPTIONAL_THEME_FIELDS = Object.freeze([
   "explicitMappingTokens",
+  // Espalier 4.7.0 menu typography: documented so the theme help covers the
+  // installed contract, optional so pulled baselines that predate it stay
+  // complete (the server seeds and requires the fields listed in
+  // DefaultSiteTheme.RequiredProperties only).
+  "fontMenu",
+  "fontWeightMenu",
   "boxBackgroundImage",
   "boxBackgroundImageOpacity",
   "vellumOpacity",
@@ -201,8 +207,12 @@ const THEME_GROUPS = Object.freeze([
       ...["fontBody", "fontHeadings", "fontBrand", "fontMonospace"].map((name) =>
         themeField(name, "CSS font-family; empty inherits the consuming surface's fallback.")
       ),
-      ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace"].map((name) =>
-        themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword.")
+      themeField(
+        "fontMenu",
+        "CSS font-family for navigation menu items and group labels; empty falls back to fontBody, never to headings.",
+      ),
+      ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace", "fontWeightMenu"].map(
+        (name) => themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword."),
       ),
       themeField("rootFontSize", "Root font size in px.", { minimum: 1, warningMaximum: 100 }),
       themeField("typeRatio", "Modular type-scale ratio.", { exclusiveMinimum: 1, warningMaximum: 1.3 }),
@@ -330,6 +340,18 @@ export function getAppearanceReference() {
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
       "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting.",
+    headerWidthContract:
+      "headerWidth 'contained' keeps the brand and the header buttons at the page content edges; "
+      + "'wide' moves them to the viewport edges. Pages with root-band components (image-banner) span the viewport, "
+      + "so full-bleed designs usually pair headerWidth 'wide' with headerLayout 'centered-menu', which keeps the "
+      + "brand left, the buttons right, and the navigation centered. validate prints a hint, never a failure, when a "
+      + "root-band page ships with a contained header.",
+    menuContract:
+      "navDrawerStyle 'full-screen' (the published default) opens the mobile menu over the whole viewport with the "
+      + "brand centered above large centered items and navDrawerTransition choosing how it appears (fade, slide-down, "
+      + "slide-up, slide-left, or slide-right); 'panel' keeps the side panel, which exists for application-style "
+      + "menus with many groups. fontMenu and fontWeightMenu set the navigation face the way fontBrand sets the "
+      + "brand; an empty fontMenu falls back to the body font, never to headings.",
     mutationOrder: [
       "fresh footer read plus concurrency-protected ten-color overlay",
       "default scheme, brand fonts and assets, favicon, and header scalars",
@@ -390,7 +412,7 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
   "FooterLink.label": { type: "plain-text", required: true, maximumLength: FOOTER_LIMITS.linkLabelLength },
   "FooterLink.pageResourceId": { type: "tracked-page-resource-uuid", exclusiveWith: "externalUrl" },
   "FooterLink.externalUrl": {
-    type: "absolute-http-or-https-url",
+    type: "contact-or-web-url",
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
@@ -403,7 +425,7 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
   "FooterRichTextRun.link": { type: "FooterInlineLink|null", default: null },
   "FooterInlineLink.pageResourceId": { type: "tracked-page-resource-uuid", exclusiveWith: "externalUrl" },
   "FooterInlineLink.externalUrl": {
-    type: "absolute-http-or-https-url",
+    type: "contact-or-web-url",
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
@@ -485,7 +507,9 @@ export function getFooterReference() {
     totalGroupMaximum: FOOTER_LIMITS.linkGroups,
     totalRichTextRunsMaximum: FOOTER_LIMITS.richTextRuns,
     targetRule:
-      "Each link has exactly one target: a tracked pageResourceId, or an absolute credential-free http/https externalUrl.",
+      "Each link has exactly one target: a tracked pageResourceId, or an externalUrl that is an absolute "
+      + "credential-free http/https URL, or a mailto:/tel: contact URL such as tel:+15555550123. A contact URL is "
+      + "published exactly as authored, so write the number the way it should be dialled.",
     imageRule:
       "Image ids come from pull or media upload. Feature images require alt text; background art is decorative.",
     readOnlyProjections: FOOTER_READ_ONLY_FIELDS,
@@ -577,6 +601,8 @@ export function formatPresentationReference(reference) {
       + "\n\nRead-only server projections:\n"
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
+      + "\nHeader width: " + reference.headerWidthContract
+      + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary
       + "\nFooter content guard: " + reference.footerContentGuard + "\n\nMutation order (non-atomic):\n"
       + reference.mutationOrder.map((step, index) => "  " + (index + 1) + ". " + step).join("\n")

package/src/reference-help.js

@@ -1,4 +1,19 @@
+import { readFileSync } from "node:fs";
+
+import { TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { CLI_BINARY_NAME } from "./constants.js";
+import {
+  FIXTURE_CONTRACT_VERSION,
+  FIXTURE_DELIVERY_ORIGIN_DOMAIN,
+  FIXTURE_MANIFEST_FILE_NAME,
+  FIXTURE_MAXIMUM_DELIVERY_ORIGINS,
+  FIXTURE_METADATA_FIELDS,
+  FIXTURE_OPTIONAL_ROOT_FIELDS,
+  FIXTURE_REQUIRED_ROOT_FIELDS,
+  SHIPPED_FIXTURE_NAME,
+  shippedFixtureDirectory,
+} from "./fixture-contract.js";
+import { SETTINGS_GROUPS } from "./settings-catalog.js";
 import {
   canonicalizeComponentData,
   COMPONENT_TYPES,
@@ -20,14 +35,21 @@ import {
 } from "./presentation-reference.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
+  MANIFEST_VERSION,
+  NAVIGATION_FILE_NAME,
   PAGE_READ_ONLY_REASON_SYSTEM_404,
+  PAGE_SOURCE_EXTENSIONS,
+  PAGE_WORKSPACE_MODE_EDITABLE,
   PAGE_WORKSPACE_MODE_READ_ONLY,
+  pageSourceFormat,
+  PAGES_DIRECTORY,
+  SETTINGS_DIRECTORY,
   SYSTEM_PAGE_NOT_FOUND_PATH,
 } from "./workspace.js";
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 15;
+export const REFERENCE_VERSION = 16;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
@@ -72,6 +94,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help footer`,
     summary: "Author and concurrency-safely push the complete footer document.",
   }),
+  Object.freeze({
+    name: "fixture",
+    usage: `${CLI_BINARY_NAME} help fixture`,
+    summary: "State the offline fixture manifest contract and locate the shipped example.",
+  }),
 ]);
 
 const WORKFLOW_REFERENCES = Object.freeze({
@@ -84,6 +111,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "kind is NAV_ITEM_KIND_PAGE, NAV_ITEM_KIND_EXTERNAL_URL, or NAV_ITEM_KIND_GROUP_HEADER.",
       "PAGE uses resourceId from .taproot-site-manifest.json, never pageId or path.",
       "EXTERNAL_URL uses externalUrl; GROUP_HEADER has no target; every kind may carry children.",
+      "externalUrl is an absolute credential-free http/https URL, or a mailto:/tel: contact URL such as "
+      + "tel:+15555550123, published exactly as authored.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",
@@ -125,6 +154,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
     details: Object.freeze([
       "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.",
       "Creation prints pageId, snapshotId, and expiresAt before the bounded render wait starts.",
       "The default stored-preview cap is 10 per authoring key and site; operators can tune it.",
       "Success returns READY with url, snapshotId, expiresAt, storedPreviewCap, storedPreviewCount, and evictedPreviews.",
@@ -134,10 +164,96 @@ const WORKFLOW_REFERENCES = Object.freeze({
     ]),
     example: Object.freeze({ command: `${CLI_BINARY_NAME} preview page classes` }),
   }),
+  fixture: Object.freeze({
+    title: "Offline fixture manifest contract",
+    summary:
+      `${FIXTURE_MANIFEST_FILE_NAME} binds a directory laid out like a pulled workspace to deterministic identities, `
+      + "so validate can prove it with no credential, no network, and no write.",
+    usage: `${CLI_BINARY_NAME} validate <fixture-directory>`,
+    details: Object.freeze([
+      `Required root fields: ${FIXTURE_REQUIRED_ROOT_FIELDS.join(", ")}.`,
+      `Accepted and not read: ${FIXTURE_OPTIONAL_ROOT_FIELDS.join(", ")} — pull writes them, and neither the snapshot `
+      + "time nor a recorded deployment can be checked offline. Any other root field is refused.",
+      `manifestVersion must be ${MANIFEST_VERSION}; fixture.contractVersion must be ${FIXTURE_CONTRACT_VERSION}.`,
+      "siteId, every pageId and resourceId, every settings entityId, and every fixture.imageIds entry is a canonical "
+      + "lowercase UUID. They are deterministic fixture identities, not identities from a live site.",
+      `Each pages[] entry binds one editable free-form source: pageId, resourceId, path, title, templateType `
+      + `${TEMPLATE_TYPE_FREE_FORM}, file, sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. `
+      + "status, hasDraft, isGenerated, and description are recorded by pull and not read: the page key set "
+      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string.",
+      `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
+      + `the format that extension implies (${
+        PAGE_SOURCE_EXTENSIONS.map((extension) => `${extension} is '${pageSourceFormat(`page${extension}`)}'`).join(
+          ", ",
+        )
+      }).`,
+      "No two page entries share a pageId, resourceId, file, or path; every declared source must exist; every "
+      + `source under '${PAGES_DIRECTORY}/' must be declared; and each entry's path must equal the path its source `
+      + "declares — a Markdown source's front-matter 'path:' wins, and the entry's value applies only when the "
+      + "front matter omits it.",
+      "pages must declare at least one entry, pagesTruncated must be false, and settingsSkipped must be empty: a "
+      + "partial snapshot is not a fixture.",
+      `navigation binds { file: "${NAVIGATION_FILE_NAME}", items }, and items must equal the tree's own item count.`,
+      `settings binds all ${SETTINGS_GROUPS.length} authorable groups, each with settingsType, file, and entityId: ${
+        SETTINGS_GROUPS.map((group) => `${group.settingsType} to '${SETTINGS_DIRECTORY}/${group.file}'`).join("; ")
+      }.`,
+      `The fixture block carries ${FIXTURE_METADATA_FIELDS.join(", ")}. Every image a page references by imageId must `
+      + "be listed in fixture.imageIds, and every absolute delivery URL a page uses must sit on a declared origin.",
+      `Each deliveryOrigins entry is an origin-only HTTPS URL (no path, query, fragment, or credentials) on `
+      + `${FIXTURE_DELIVERY_ORIGIN_DOMAIN} or a subdomain of it, at most ${FIXTURE_MAXIMUM_DELIVERY_ORIGINS} of them, `
+      + "with no duplicates. Fixtures are copied and shipped, so a real delivery host in one would be a live "
+      + "reference in every copy.",
+      "validate reads the fixture and writes nothing to it. Copy the directory somewhere writable before editing it.",
+    ]),
+  }),
 });
 
+// The box, rather than the value, is the cache: an absent fixture memoizes
+// `undefined` instead of being re-read on every call.
+let shippedFixtureManifestCache;
+
+/**
+ * The shipped fixture's own manifest, read on demand and memoized, or
+ * `undefined` when this copy of the package has no readable `examples/`.
+ *
+ * The read is lazy because `examples/` ships but is not load-bearing. This
+ * module sits on the path of every verb (`bin/taproot-site.js` imports
+ * `src/cli.js`, which imports this) and of every library consumer through
+ * `src/index.js`, while `examples/` is exactly what a `node_modules` pruner or
+ * an image-slimming step drops. A static import would turn such a pruned
+ * install into an `ERR_MODULE_NOT_FOUND` at module load for `login`, `pull`,
+ * `push`, and every other verb; reading here degrades `help fixture` alone.
+ */
+function shippedFixtureManifest() {
+  shippedFixtureManifestCache ??= { value: readShippedFixtureManifest() };
+  return shippedFixtureManifestCache.value;
+}
+
+function readShippedFixtureManifest() {
+  try {
+    return JSON.parse(readFileSync(
+      new URL(`../examples/${SHIPPED_FIXTURE_NAME}/${FIXTURE_MANIFEST_FILE_NAME}`, import.meta.url),
+      "utf8",
+    ));
+  } catch {
+    // Missing, unreadable, or not JSON. The contract the topic states is
+    // derived from constants and stays complete without an example, so
+    // `help fixture` answers rather than fails.
+    return undefined;
+  }
+}
+
 export function getWorkflowReference(topic) {
-  return WORKFLOW_REFERENCES[topic];
+  const reference = WORKFLOW_REFERENCES[topic];
+  if (topic !== "fixture") return reference;
+  const example = shippedFixtureManifest();
+  // The directory is resolved from this package rather than from the caller's
+  // directory, so the path is right for a global install as well as a
+  // checkout. Both it and the example are reported only when the fixture is
+  // actually present: a pruned install has nothing to locate or to validate.
+  return example === undefined
+    ? reference
+    : Object.freeze({ ...reference, fixtureDirectory: shippedFixtureDirectory(), example });
 }
 
 function componentSummary(type) {
@@ -324,6 +440,8 @@ function decorationReference() {
 }
 
 const INLINE_FACTS_DEFINITION = FREE_FORM_SECTION_REGISTRY.inlineFacts;
+// The third fact carries no label on purpose: a phone number names itself, and
+// the row is allowed to mix labelled and standalone facts.
 const INLINE_FACT_ITEMS_EXAMPLE = Object.freeze([
   Object.freeze({ value: "4.9 ★", label: "Community rating" }),
   Object.freeze({
@@ -331,7 +449,7 @@ const INLINE_FACT_ITEMS_EXAMPLE = Object.freeze([
     label: "Elm Harbor",
     url: "https://maps.example.test/?q=100%20Riverside%20Way%20Elm%20Harbor",
   }),
-  Object.freeze({ value: "(555) 013-7788", label: "Call the studio", url: "tel:+15550137788" }),
+  Object.freeze({ value: "(555) 013-7788", url: "tel:+15550137788" }),
   Object.freeze({ value: "Open today until 8:30 PM", label: "Today's hours", url: "/classes" }),
 ]);
 
@@ -353,6 +471,12 @@ function inlineFactsReference() {
       }),
     }),
     placement: Object.freeze({ ...INLINE_FACTS_DEFINITION.placement }),
+    valuePolicy:
+      `Required non-whitespace plain text; maximum ${items.fields.value.maxScalars} Unicode scalar values.`,
+    labelPolicy:
+      `Optional non-whitespace plain text; maximum ${items.fields.label.maxScalars} Unicode scalar values. `
+      + "Omit it when the value already names itself, such as a rating, an address, or a phone number; a row may "
+      + "mix labelled and standalone facts. An empty string is rejected, so omitting a label stays explicit.",
     urlPolicy:
       "Optional safe HTTP(S), mailto, tel, non-protocol-relative root, fragment, query, or relative URL. Empty/whitespace-only values, other schemes, backslashes, and ASCII controls are rejected; tel: remains a native link.",
     markdown: Object.freeze({
@@ -897,7 +1021,7 @@ export function formatReferenceResult(result) {
         page.sections.placementMatrix.map(formatPlacement).join("\n")
       }\n\nSemantic tables:\n  placement             document root or directly inside a top-level section; wide/full-well measure\n  rows                  exactly ${page.tables.structure.headerRows} header row, then ${page.tables.limits.dataRows.min} through ${page.tables.limits.dataRows.max} data rows\n  columns               ${page.tables.limits.columns.min} through ${page.tables.limits.columns.max}; delimiter and every row must match the header width\n  caption               optional non-empty plain text; maximum ${page.tables.limits.captionScalars.max} Unicode scalar values; syntax ${page.tables.markdown.captionSyntax}\n  caption guidance      ${page.tables.captionGuidance}\n  cells                 exactly ${page.tables.structure.paragraphChildrenPerCell} paragraph; headers need non-whitespace text; data cells may be empty; maximum ${page.tables.limits.cellTextScalars.max} text scalars\n  inline                ${page.tables.structure.inlineNodes.join(", ")}; marks ${page.tables.structure.marks.join(", ")}\n  pipes                 outer pipes ${page.tables.markdown.outerPipes}; write a literal pipe as ${page.tables.markdown.literalPipeEscape}\n  spans                 unsupported: ${page.tables.structure.unsupportedSpanAttrs.join(", ")}\n  alignment             ${page.tables.markdown.alignment}; delimiter cells contain hyphens only\n  termination           a blank line ends the table before another block\n\nRate table example:\n${page.tables.examples.rateTable}\n\nComparison table example:\n${page.tables.examples.comparisonTable}\n\nRejected alignment example (${CONTENT_ERROR_CODES.markdownTableAlignment}):\n${page.tables.examples.rejectedAlignment}\nRemove the ':' characters from the delimiter row.\n\nDirect ProseMirror table example:\n${JSON.stringify(page.tables.examples.proseMirror, null, 2)}\n\nTable error corrections:\n${
         page.tables.corrections.map((entry) => `  ${entry.code.padEnd(34)} ${entry.correction}`).join("\n")
-      }\n\nInline facts:\n  placement             document root or directly inside a top-level section; ${page.inlineFacts.placement.measure} measure\n  items                 ${page.inlineFacts.attrs.items.minItems} through ${page.inlineFacts.attrs.items.maxItems}; closed objects in value, label, url order\n  value and label       required non-whitespace plain text; maximum ${page.inlineFacts.attrs.items.fields[0].maxScalars} Unicode scalar values each\n  url                   ${page.inlineFacts.urlPolicy}\n  Markdown              fenced ${page.inlineFacts.markdown.fence} block whose body is a JSON array\n\nInline-facts Markdown example:\n${page.inlineFacts.markdown.example}\n\nDirect ProseMirror inlineFacts example:\n${JSON.stringify(page.inlineFacts.examples.proseMirror, null, 2)}\n\nRaw HTML: ${page.document.rawHtml.default} by default. For a tracked ${page.document.rawHtml.trackedProseMirror.format} document only: ${page.document.rawHtml.trackedProseMirror.behavior} Opt in with ${page.document.rawHtml.trackedProseMirror.optIn}. For ${page.document.rawHtml.markdown.format}, ${page.document.rawHtml.markdown.behavior} ${page.document.rawHtml.warning}\n\nComponents:\n${
+      }\n\nInline facts:\n  placement             document root or directly inside a top-level section; ${page.inlineFacts.placement.measure} measure\n  items                 ${page.inlineFacts.attrs.items.minItems} through ${page.inlineFacts.attrs.items.maxItems}; closed objects in ${page.inlineFacts.attrs.items.itemFieldOrder.join(", ")} order\n  value                 ${page.inlineFacts.valuePolicy}\n  label                 ${page.inlineFacts.labelPolicy}\n  url                   ${page.inlineFacts.urlPolicy}\n  Markdown              fenced ${page.inlineFacts.markdown.fence} block whose body is a JSON array\n\nInline-facts Markdown example:\n${page.inlineFacts.markdown.example}\n\nDirect ProseMirror inlineFacts example:\n${JSON.stringify(page.inlineFacts.examples.proseMirror, null, 2)}\n\nRaw HTML: ${page.document.rawHtml.default} by default. For a tracked ${page.document.rawHtml.trackedProseMirror.format} document only: ${page.document.rawHtml.trackedProseMirror.behavior} Opt in with ${page.document.rawHtml.trackedProseMirror.optIn}. For ${page.document.rawHtml.markdown.format}, ${page.document.rawHtml.markdown.behavior} ${page.document.rawHtml.warning}\n\nComponents:\n${
         page.components.map((component) => `  ${component.type.padEnd(16)} ${component.summary}`).join("\n")
       }\n\nWorkflow:\n${
         page.workflow.map((step) => `  ${step.command}: ${step.result}`).join("\n")
@@ -915,9 +1039,20 @@ export function formatReferenceResult(result) {
     }
     case "workflow": {
       const reference = result.reference;
-      return `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n\n${
+      // Only the fixture reference carries a shipped directory; every other
+      // workflow topic renders exactly as it did.
+      const shipped = reference.fixtureDirectory === undefined
+        ? ""
+        : `\nShipped example: ${reference.fixtureDirectory}\nValidate it: ${CLI_BINARY_NAME} validate "${reference.fixtureDirectory}"\n`;
+      // Every other topic's example is a literal in this module and is always
+      // present; the fixture topic's is a shipped file, so it is omitted the
+      // same way the shipped-directory lines are when the file is not there.
+      const example = reference.example === undefined
+        ? ""
+        : `\n\nExample:\n${JSON.stringify(reference.example, null, 2)}`;
+      return `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n${shipped}\n${
         reference.details.map((detail) => `  - ${detail}`).join("\n")
-      }\n\nExample:\n${JSON.stringify(reference.example, null, 2)}\n`;
+      }${example}\n`;
     }
     case "presentation":
       return formatPresentationReference(result.reference);

package/src/settings-catalog.js

@@ -58,6 +58,8 @@ export const SETTINGS_GROUPS = Object.freeze([
         "defaultScheme",
         "fontBrand",
         "fontWeightBrand",
+        "fontMenu",
+        "fontWeightMenu",
         "lightLogoId",
         "lightLogoUrl",
         "darkLogoId",
@@ -86,6 +88,9 @@ export const SETTINGS_GROUPS = Object.freeze([
     fields: Object.freeze([
       ...stringFields(
         "headerLayout",
+        "headerWidth",
+        "navDrawerStyle",
+        "navDrawerTransition",
         "brandText",
         "brandColor",
         "logoAlt",

package/src/transport.js

@@ -1,4 +1,6 @@
 import {
+  CAPABILITY_REFUSAL_FIELD,
+  CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
@@ -9,6 +11,7 @@ import {
   LIMITS,
   PLAN_LIMIT_REFUSAL_FIELD,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_CAPABILITY_MISSING,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_PLATFORM_PAUSED,
@@ -330,21 +333,95 @@ function fieldDescriptions(value) {
   return descriptions;
 }
 
+/**
+ * A delegation capability or permission key as the server spells it. Anything
+ * outside this shape is dropped rather than repaired: these values reach a
+ * terminal and a machine-readable result, and a name the CLI cannot vouch for
+ * is worse than a name it does not print.
+ */
+const CAPABILITY_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/u;
+const MAXIMUM_CAPABILITY_NAMES = 16;
+
+function capabilityNames(value) {
+  if (typeof value !== "string" || value === "") return [];
+  return value
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length <= 200 && CAPABILITY_NAME.test(name))
+    .slice(0, MAXIMUM_CAPABILITY_NAMES);
+}
+
+/**
+ * The key-mode capability denial the authoring API attaches as a
+ * `google.rpc.ErrorInfo` detail (TR00691), or undefined.
+ *
+ * The same bounded breadth-first walk the field extractors use, for the same
+ * reason: transcoded `details[]` entries are `Any`-packed, and pinning one path
+ * through them is how a contract change silently empties an extractor. The
+ * `reason` is the contract — a stable, namespaced classifier — so the walk
+ * keys on it rather than on `@type`, which a future packing could reshape.
+ */
+export function capabilityRefusal(value) {
+  const queue = [{ value, depth: 0 }];
+  let work = 0;
+  while (queue.length > 0 && work < 1_000) {
+    const current = queue.shift();
+    work += 1;
+    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
+    const metadata = current.value.metadata;
+    if (
+      current.value.reason === CAPABILITY_REFUSAL_REASON
+      && metadata !== null
+      && typeof metadata === "object"
+      && !Array.isArray(metadata)
+    ) {
+      const permission = capabilityNames(metadata.permission)[0];
+      // A detail naming no permission is not this refusal, whatever it says:
+      // the guidance is built entirely out of these three values, and half of
+      // one would be a message nobody could act on.
+      if (permission !== undefined) {
+        return Object.freeze({
+          permission,
+          granted: Object.freeze(capabilityNames(metadata.granted)),
+          required: Object.freeze(capabilityNames(metadata.required)),
+        });
+      }
+    }
+    for (const child of Object.values(current.value)) {
+      if (child !== null && typeof child === "object") queue.push({ value: child, depth: current.depth + 1 });
+    }
+  }
+  return undefined;
+}
+
 export class ApiError extends SiteAuthoringError {
   constructor(httpStatus, body) {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
+    const capability = capabilityRefusal(body);
     super(
       "api.request_rejected",
       fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
+        : capability !== undefined
+        ? `Taproot refused the request: this credential does not carry a capability granting '${
+          capability.permission
+        }'.`
         : `Taproot rejected the request with HTTP ${httpStatus}.`,
-      { field: fields[0], status: grpcCode === undefined ? `http:${httpStatus}` : `grpc:${grpcCode}` },
+      {
+        // `fields` stays exactly what the wire named. The capability field is
+        // the CLI's own label for a refusal that carries no field violation at
+        // all, so it lands on the error without joining the wire-derived set
+        // that `hasField()` classifies on.
+        field: fields[0] ?? (capability === undefined ? undefined : CAPABILITY_REFUSAL_FIELD),
+        status: grpcCode === undefined ? `http:${httpStatus}` : `grpc:${grpcCode}`,
+      },
     );
     this.httpStatus = httpStatus;
     this.grpcCode = grpcCode;
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
+    this.capability = capability;
   }
 
   hasField(field) {
@@ -366,7 +443,7 @@ export class ApiError extends SiteAuthoringError {
 
   /**
    * Classifies a refusal into the one thing the caller should do next. The
-   * four kinds are genuinely different behaviors, and collapsing them into
+   * five kinds are genuinely different behaviors, and collapsing them into
    * "the request failed" is what makes an agent retry a revoked credential
    * forever or treat a plan ceiling as a transient outage:
    *
@@ -393,6 +470,13 @@ export class ApiError extends SiteAuthoringError {
    *   never invents the numeric limit.
    * - `throttled` (gRPC `ResourceExhausted` / HTTP 429) — the per-key
    *   throttle. **Back off** and retry with delay.
+   * - `capability_missing` (`ErrorInfo` reason `SITE_AUTHORING_CAPABILITY_MISSING`)
+   *   — the credential is valid and correctly scoped, and simply was not
+   *   exchanged for a capability this request needs. **Fix the verb table**,
+   *   not the credential: the exchange minted exactly what the verb asked for,
+   *   so a verb whose declared set is short of the requests it makes is the
+   *   defect. Distinguished from `credential_rejected` precisely because
+   *   re-issuing the same credential cannot help (TR00691).
    *
    * Anything else is `unclassified`, which is a signal to surface the raw
    * status rather than to guess.
@@ -403,6 +487,9 @@ export class ApiError extends SiteAuthoringError {
     if (this.hasField(ROLLOUT_REFUSAL_FIELD)) return REFUSAL_PLATFORM_PAUSED;
     if (this.hasField(CREDENTIAL_REFUSAL_FIELD)) return REFUSAL_CREDENTIAL_REJECTED;
     if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD)) return REFUSAL_PLAN_LIMIT;
+    // The named detail ranks with the fields and above the status mappings, for
+    // the same reason: it is the specific statement about this refusal.
+    if (this.capability !== undefined) return REFUSAL_CAPABILITY_MISSING;
     if (this.grpcCode === GRPC_RESOURCE_EXHAUSTED || this.httpStatus === HTTP_TOO_MANY_REQUESTS) {
       return REFUSAL_THROTTLED;
     }

package/src/verbs/nav-push.js

@@ -9,6 +9,11 @@ import {
   withRefusalGuidance,
 } from "../api.js";
 import { VERB_NAV_PUSH } from "../constants.js";
+import {
+  CONTACT_OR_WEB_URL_MAX_LENGTH,
+  CONTACT_OR_WEB_URL_REQUIREMENT,
+  isContactOrWebUrl,
+} from "../contact-url.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult } from "../session.js";
 import {
@@ -44,7 +49,7 @@ import {
 const MAXIMUM_REPORTED = 100;
 const MAXIMUM_ITEMS = 1_000;
 const MAXIMUM_TITLE_LENGTH = 200;
-const MAXIMUM_URL_LENGTH = 2_048;
+const MAXIMUM_URL_LENGTH = CONTACT_OR_WEB_URL_MAX_LENGTH;
 const ITEM_KEYS = new Set(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
 
 // `SaveSiteNavigation` maps both `id` and `resourceId` through
@@ -141,14 +146,10 @@ function validateItem(item, itemPath, depth, seenIds, counters) {
     if (!isBoundedText(item.externalUrl, MAXIMUM_URL_LENGTH)) {
       throw navError("nav.external_url_missing", "an EXTERNAL_URL item needs a non-empty 'externalUrl'.", itemPath);
     }
-    let url;
-    try {
-      url = new URL(item.externalUrl);
-    } catch {
-      url = undefined;
-    }
-    if (url === undefined || (url.protocol !== "https:" && url.protocol !== "http:")) {
-      throw navError("nav.external_url_invalid", "'externalUrl' must be an absolute http or https URL.", itemPath);
+    // A header item may be a phone number or an email address, not just a web
+    // page; the value is stored verbatim so the number stays dialable.
+    if (!isContactOrWebUrl(item.externalUrl, MAXIMUM_URL_LENGTH)) {
+      throw navError("nav.external_url_invalid", `'externalUrl' ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, itemPath);
     }
     if (!isEmpty(item.resourceId)) {
       throw navError("nav.resource_unexpected", "an EXTERNAL_URL item must not carry 'resourceId'.", itemPath);

package/src/verbs/pull.js

@@ -9,7 +9,7 @@ import {
   TEMPLATE_TYPE_FREE_FORM,
   withRefusalGuidance,
 } from "../api.js";
-import { REFUSAL_UNCLASSIFIED, VERB_PULL } from "../constants.js";
+import { REFUSAL_CAPABILITY_MISSING, REFUSAL_UNCLASSIFIED, VERB_PULL } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { appearanceManifestEntry, footerManifestEntry } from "../footer-workspace.js";
 import { boundedList, openSession, successResult } from "../session.js";
@@ -94,8 +94,10 @@ import {
 
 const MAXIMUM_REPORTED = 200;
 // A settings group the credential's envelope does not reach is a narrower
-// snapshot, not a failed pull. Anything the transport classified as a refusal
-// is a different matter and always propagates.
+// snapshot, not a failed pull. The server names that shortfall as a
+// capability denial (TR00691), and an older server answers a bare 403; both
+// mean the same thing here. Any other classified refusal — a rejected
+// credential, the rollout switch, a plan ceiling — always propagates.
 const UNAVAILABLE_SETTINGS_STATUSES = new Set([403, 404]);
 const APPEARANCE_SETTINGS_TYPES = Object.freeze([
   SETTINGS_TYPE_TAPROOT_STYLES,
@@ -435,7 +437,8 @@ export async function pull(invocation) {
       } catch (error) {
         if (
           error instanceof ApiError
-          && error.refusalKind() === REFUSAL_UNCLASSIFIED
+          && (error.refusalKind() === REFUSAL_UNCLASSIFIED
+            || error.refusalKind() === REFUSAL_CAPABILITY_MISSING)
           && UNAVAILABLE_SETTINGS_STATUSES.has(error.httpStatus)
         ) {
           onProgress(`Settings group ${group.settingsType} is not readable by this credential; skipping it.`);