@taprootio/site-authoring 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -22,6 +22,7 @@
   },
   "files": [
     "bin/",
+    "examples/",
     "src/",
     "LICENSE",
     "README.md"

package/src/api.js

@@ -1,6 +1,8 @@
 import {
   CANONICAL_TIMESTAMP,
+  CAPABILITY_REFUSAL_FIELD,
   LIMITS,
+  REFUSAL_CAPABILITY_MISSING,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_PLATFORM_PAUSED,
@@ -329,6 +331,32 @@ const REFUSAL_GUIDANCE = Object.freeze({
 export function announceRefusal(error, onProgress, action = "request") {
   if (!(error instanceof ApiError)) return;
   const kind = error.refusalKind();
+  if (kind === REFUSAL_CAPABILITY_MISSING) {
+    const { permission, granted, required } = error.capability;
+    onProgress("");
+    onProgress(`CAPABILITY MISSING (refusal=${REFUSAL_CAPABILITY_MISSING}, field=${CAPABILITY_REFUSAL_FIELD})`);
+    onProgress(
+      `  Taproot refused this ${action} because the credential it runs on was not exchanged for a capability `
+        + `that grants '${permission}'.`,
+    );
+    onProgress(`  Granted: ${granted.length > 0 ? granted.join(", ") : "(none)"}.`);
+    onProgress(
+      required.length > 0
+        ? `  Carried by: ${required.join(", ")}.`
+        : "  Carried by: no site-authoring capability — this permission is not reachable by any credential.",
+    );
+    // The credential is exactly what was asked for, so re-issuing it changes
+    // nothing. What is wrong is the verb's declared capability set, and saying
+    // so is the whole point of the named refusal: the first agent to meet this
+    // had to read the package source to find out.
+    onProgress(
+      `  The credential is not the problem: the exchange minted precisely what the ${action} asked for. `
+        + "The verb's declared capability set in the CLI's verb table is short of the requests it makes; "
+        + "report it rather than minting a wider key.",
+    );
+    onProgress("");
+    return;
+  }
   if (kind === REFUSAL_PLAN_LIMIT) {
     onProgress("");
     onProgress("PLAN LIMIT (refusal=plan_limit, field=UpgradePrompt)");

package/src/cli.js

@@ -75,7 +75,9 @@ const VERBS = Object.freeze([
     offline: true,
     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.",
+      + "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.",
   },
   {
     name: VERB_LOGIN,
@@ -210,7 +212,10 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_NAV_PUSH,
-    capabilities: [CAPABILITY_DESIGN],
+    // Content is for the read, not the write: every PAGE nav item is checked
+    // against the live page list before the tree is replaced, and that list is
+    // gated on site.pages.edit_any (TR00691).
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
     tokens: ["nav", "push"],
     summary: "Replace the whole navigation tree from the local workspace.",
   },
@@ -251,7 +256,18 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_DEPLOY,
-    capabilities: [CAPABILITY_DEPLOYMENTS],
+    // 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.
+    // 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,
+    // which only Design carries. Every candidate this CLI stages from a pulled
+    // workspace carries settings, navigation, or both, so a promotion without
+    // Design is refused.
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN, CAPABILITY_DEPLOYMENTS],
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
@@ -265,6 +281,8 @@ const VERBS = Object.freeze([
     json: true,
     note: "Select the persisted draft by page path (as recorded by pull) or canonical lowercase UUID. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
+      + "Preview before approving: approve consumes the draft, so a page that has been approved has no draft "
+      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. "
       + "The handoff URL in the result is single-use and expires two minutes after it is minted: opening it "
       + "consumes it, and a reused, shared, or bookmarked preview URL answers Not found. Run preview page again "
       + "for another. "
@@ -293,6 +311,23 @@ const VERBS = Object.freeze([
   },
 ]);
 
+/**
+ * The shipped verb table's capability declarations, keyed by verb name.
+ *
+ * Exported so the tests enforce the table rather than restate it. The claim
+ * each entry makes — "this is the smallest set this verb's requests need" —
+ * went four releases without anything checking it, and it was wrong twice:
+ * `nav push` and `deploy` were each short of a read they make on every run, and
+ * `deploy` was short again of the promotion re-authorization the server runs on
+ * state the request only names (TR00691). A verb with no entry needs no site
+ * credential at all.
+ */
+export const VERB_CAPABILITIES = Object.freeze(Object.fromEntries(
+  VERBS
+    .filter((verb) => verb.capabilities !== undefined)
+    .map((verb) => [verb.name, Object.freeze([...verb.capabilities])]),
+));
+
 const COMMON_OPTIONS = `Options:
   --config <path>  Place before a config-reading verb; bypass parent discovery.
   --quiet          Suppress human progress. The JSON result is unchanged.
@@ -464,6 +499,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "theme"
       || topic === "appearance"
       || topic === "footer"
+      || topic === "fixture"
     )
     && (subject !== undefined || extra.length > 0)) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
@@ -515,6 +551,7 @@ function referenceResult(parsed) {
     case "nav":
     case "media":
     case "preview":
+    case "fixture":
       return { ...result, topic: "workflow", referenceKind: parsed.topic, reference: getWorkflowReference(parsed.topic) };
     case "theme":
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
@@ -750,9 +787,16 @@ function parseArguments(arguments_) {
   return {
     mode: "run",
     verb: verb.name,
-    // The smallest capability set this verb's requests need. It reaches the
-    // exchange so a content push never holds deploy, and a pull never holds
-    // delete (TR00645).
+    // The smallest capability set this verb's requests need — every permission
+    // 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
+    // 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
+    // verb actually calls.
     capabilities: verb.capabilities,
     configPath,
     quiet,

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.3.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -99,7 +99,7 @@ export const DEPLOY_TARGET_STAGING = "staging";
 export const DEPLOY_TARGET_PRODUCTION = "production";
 
 /**
- * The refusal vocabulary TR00602/TR00603 speak, collapsed into the four
+ * The refusal vocabulary TR00602/TR00603/TR00691 speak, collapsed into the five
  * distinct client behaviors plus an explicit "we do not know" value. The CLI
  * keeps these apart because an agent's correct next move differs for each:
  * see `ApiError.refusalKind()` in transport.js.
@@ -108,6 +108,7 @@ export const REFUSAL_PLATFORM_PAUSED = "platform_paused";
 export const REFUSAL_CREDENTIAL_REJECTED = "credential_rejected";
 export const REFUSAL_PLAN_LIMIT = "plan_limit";
 export const REFUSAL_THROTTLED = "throttled";
+export const REFUSAL_CAPABILITY_MISSING = "capability_missing";
 export const REFUSAL_UNCLASSIFIED = "unclassified";
 
 export const REFUSAL_KINDS = Object.freeze([
@@ -115,6 +116,7 @@ export const REFUSAL_KINDS = Object.freeze([
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_THROTTLED,
+  REFUSAL_CAPABILITY_MISSING,
   REFUSAL_UNCLASSIFIED,
 ]);
 
@@ -125,6 +127,25 @@ export const ROLLOUT_REFUSAL_FIELD = "SiteAuthoringRollout";
 export const CREDENTIAL_REFUSAL_FIELD = "ExternalApiKey";
 export const PLAN_LIMIT_REFUSAL_FIELD = "UpgradePrompt";
 
+/**
+ * The `google.rpc.ErrorInfo` reason a key-mode permission denial carries
+ * (TR00691, `SiteAuthoringKeyDenial` on the server). A wire identity, matched
+ * exactly.
+ */
+export const CAPABILITY_REFUSAL_REASON = "SITE_AUTHORING_CAPABILITY_MISSING";
+
+/**
+ * The `field` a capability refusal reports on the JSON error.
+ *
+ * The server sends this refusal as `ErrorInfo`, not as a field violation — the
+ * request is well formed and the credential is too narrow, so a `BadRequest`
+ * would misstate the status. Automation still wants one shape to branch on, so
+ * the CLI names the field itself, exactly as `platform_paused` carries
+ * `SiteAuthoringRollout`. It is the CLI's own label rather than a value read
+ * off the wire, which is why nothing matches an incoming field against it.
+ */
+export const CAPABILITY_REFUSAL_FIELD = "GrantedCapabilities";
+
 // gRPC `ResourceExhausted`. Transcoded responses carry the numeric code in the
 // body; the HTTP mapping is 429.
 export const GRPC_RESOURCE_EXHAUSTED = 8;

package/src/contact-url.js

@@ -0,0 +1,63 @@
+import { hasControlCharacter } from "./errors.js";
+
+/**
+ * The one rule for an outbound target on a footer link or a navigation item.
+ *
+ * A local business's phone number and address are the two things a visitor
+ * looks for in a header and a footer, and page links have accepted `tel:` and
+ * `mailto:` since D12. This is the same permissive scheme set the published
+ * renderer already applies to page content (`generator/src/url-safety.ts`,
+ * `shared/tiptap-prosemirror.ts`, `ux/client/src/common/sanitize-html.ts`),
+ * narrowed to what a *stored* target may be: absolute, so there is no base to
+ * resolve against at publish time, and credential-free, so a footer cannot
+ * carry someone's password into published HTML.
+ *
+ * `tel:` and `mailto:` are opaque URLs whose body is content — a number with
+ * its punctuation, an address with its plus-tag. Callers emit the value
+ * verbatim after this check rather than round-tripping it through
+ * `URL.toString()`, which re-encodes both.
+ */
+
+/** Longest external target a footer link or a navigation item may carry. */
+export const CONTACT_OR_WEB_URL_MAX_LENGTH = 2_048;
+
+/**
+ * The requirement clause every layer says when it refuses a target, so the
+ * CLI, the editors, and the server all name the same four schemes.
+ */
+export const CONTACT_OR_WEB_URL_REQUIREMENT =
+  "must be an absolute http or https URL without credentials, or a mailto or tel contact URL";
+
+const WEB_PROTOCOLS = new Set(["http:", "https:"]);
+const CONTACT_PROTOCOLS = new Set(["mailto:", "tel:"]);
+
+/**
+ * Whether `value` is a target the footer and navigation contracts accept.
+ *
+ * ASCII controls, C1 controls, and backslashes are refused before the scheme
+ * is looked at: browsers normalize them inconsistently, and a line break in a
+ * `mailto:` is the header-injection vector.
+ */
+export function isContactOrWebUrl(value, maximumLength = CONTACT_OR_WEB_URL_MAX_LENGTH) {
+  if (typeof value !== "string" || value.length === 0 || value.length > maximumLength) return false;
+  if (hasControlCharacter(value) || value.includes("\\")) return false;
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (WEB_PROTOCOLS.has(parsed.protocol)) {
+    return parsed.username === "" && parsed.password === "" && parsed.hostname !== "";
+  }
+  // The body is everything after `tel:` or `mailto:`; an empty one is a link
+  // to nothing, which publishes as a dead anchor rather than a refusal. A
+  // body that opens with `//` is an authority, which a contact URL has no use
+  // for, and the four layers agree on refusing it rather than on how each
+  // parser validates one.
+  return CONTACT_PROTOCOLS.has(parsed.protocol)
+    && parsed.pathname !== ""
+    && !value.slice(value.indexOf(":") + 1).startsWith("//");
+}

package/src/content/components.js

@@ -149,7 +149,11 @@ const CTA = Object.freeze({
   buttonText: str(),
   buttonUrl: actionUrl(),
   variant: enumOf("primary", "danger"),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around the call-to-action panel; 0 leaves it unbordered.",
+  }),
   imagePosition: enumOf("top", "left", "right"),
   mediaImage: image(),
 });
@@ -167,7 +171,11 @@ const FEATURE_GRID = Object.freeze({
   ),
   columns: num({ values: Object.freeze([2, 3, 4]) }),
   iconSize: enumOf("small", "medium", "large", "xlarge"),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around each item, as on a card grid; the grid itself is never framed. 0 boxes nothing.",
+  }),
 });
 
 /** `TestimonialData` and its `TestimonialItem`. */
@@ -184,7 +192,11 @@ const TESTIMONIAL = Object.freeze({
   columns: num({ values: Object.freeze([1, 2, 3]) }),
   carousel: bool(),
   interval: num({ integer: true, minimum: 2000 }),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around the whole set of quotations — the grid or the carousel; 0 leaves it unbordered.",
+  }),
 });
 
 /** `LatestPostsData` — resolved at generation time. */
@@ -212,7 +224,11 @@ const CARD_GRID = Object.freeze({
     { kind: "value", value: Object.freeze([]) },
   ),
   columns: num({ values: Object.freeze([2, 3]) }),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around each card; the grid itself is never framed. 0 boxes nothing.",
+  }),
 });
 
 /** `ImageBannerData`. */
@@ -372,6 +388,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "Each linked item needs a title that remains meaningful as link text.",
       "Icon images need descriptive alt text when they convey information; otherwise use an empty alt value.",
+      "Item title and description are plain text: an item's url makes the whole item the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
     ],
     {
       items: [
@@ -428,6 +445,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "Every linked card needs a title that describes its destination.",
       "Card images need descriptive alt text unless they are decorative.",
+      "Card title and description are plain text: a card's linkUrl makes the whole card the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
     ],
     {
       cards: [
@@ -544,6 +562,10 @@ function referenceSchema(spec) {
       if (spec.values) schema.enum = [...spec.values];
       if (spec.minimum !== undefined) schema.minimum = spec.minimum;
       if (spec.maximum !== undefined) schema.maximum = spec.maximum;
+      // A numeric field whose units say nothing about what the number does —
+      // `borderWidth` is the case — carries its meaning here so `help
+      // component` prints it beside the constraints.
+      if (spec.description) schema.description = spec.description;
       return schema;
     }
     case "array":

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

@@ -370,7 +370,7 @@
   "inlineFacts": {
     "nodeType": "inlineFacts",
     "label": "Inline facts",
-    "help": "A compact ordered row of labeled facts whose values may be native links.",
+    "help": "A compact ordered row of facts whose values may be native links. A fact that names itself needs no label.",
     "attrs": {
       "items": {
         "type": "array",
@@ -388,7 +388,8 @@
           },
           "label": {
             "type": "plain-text",
-            "required": true,
+            "required": false,
+            "default": null,
             "minScalars": 1,
             "maxScalars": 120,
             "nonWhitespace": true

package/src/content/inline-facts.js

@@ -64,9 +64,13 @@ export function normalizeInlineFactsItems(
       }
     }
 
+    // The value is the fact; the label names it when the value does not name
+    // itself. An omitted or null label is the standalone fact, while an empty
+    // string stays refused so a half-authored item is still caught.
     for (const name of ["value", "label"]) {
       const field = definition.fields[name];
       const entry = item[name];
+      if (!field.required && (entry === undefined || entry === null)) continue;
       if (typeof entry !== "string" || (field.nonWhitespace && entry.trim() === "")) {
         report(`${itemPath}/${name}`, CODES.attrInvalid, `Inline fact ${name} must contain non-whitespace text.`);
       } else if (scalarLength(entry, field.maxScalars) > field.maxScalars) {
@@ -88,7 +92,7 @@ export function normalizeInlineFactsItems(
 
     items.push(Object.freeze({
       value: item.value,
-      label: item.label,
+      ...(typeof item.label === "string" ? { label: item.label } : {}),
       ...(typeof item.url === "string" ? { url: item.url.trim() } : {}),
     }));
   });

package/src/content/tiptap-prosemirror.ts

@@ -496,10 +496,20 @@ function countUnicodeScalars(value: string): number {
 
 type NormalizedInlineFact = {
   value: string;
-  label: string;
+  label?: string;
   url?: string;
 };
 
+/**
+ * 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
+ * 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
+ * not rendered, so the row looks the same.
+ */
 function renderInlineFacts(
   node: ProseMirrorNode,
   options: RenderProseMirrorOptions,
@@ -512,17 +522,18 @@ function renderInlineFacts(
     const value = fact.url
       ? renderElement("a", { href: fact.url }, escapeHtml(fact.value))
       : escapeHtml(fact.value);
+    const label = fact.label === undefined
+      ? ""
+      : `${renderElement("span", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))} `;
     return renderElement(
-      "div",
-      { class: "taproot-inline-fact" },
-      `${renderElement("dt", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))}${
-        renderElement("dd", { class: "taproot-inline-fact__value" }, value)
-      }`,
+      "li",
+      { class: "taproot-inline-fact", role: "listitem" },
+      `${label}${renderElement("span", { class: "taproot-inline-fact__value" }, value)}`,
     );
   }).join("");
   return renderElement(
-    "dl",
-    withProseMeasure({ class: "taproot-inline-facts" }, node.type, options),
+    "ul",
+    withProseMeasure({ class: "taproot-inline-facts", role: "list" }, node.type, options),
     items,
   );
 }
@@ -544,14 +555,17 @@ function normalizeInlineFacts(node: ProseMirrorNode): NormalizedInlineFact[] | u
   for (const value of node.attrs.items) {
     if (!isRecord(value) || !hasOnlyKeys(value, fieldKeys)) return undefined;
     const factValue = stringAttr(value.value);
-    const label = stringAttr(value.label);
     if (
       !factValue
-      || !label
       || factValue.trim() === ""
-      || label.trim() === ""
       || countUnicodeScalars(factValue) > definition.fields.value.maxScalars
-      || countUnicodeScalars(label) > definition.fields.label.maxScalars
+    ) return undefined;
+    // An omitted or null label is the standalone fact; an empty string is a
+    // half-authored one and still fails the row closed.
+    const label = value.label === undefined || value.label === null ? undefined : stringAttr(value.label);
+    if (
+      value.label !== undefined && value.label !== null
+      && (!label || label.trim() === "" || countUnicodeScalars(label) > definition.fields.label.maxScalars)
     ) return undefined;
     const url = value.url === undefined || value.url === null ? undefined : stringAttr(value.url);
     if (value.url !== undefined && value.url !== null && (!url || !isSafeUrl(url))) return undefined;

package/src/fixture-contract.js

@@ -0,0 +1,63 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * The offline authoring-fixture contract (TR00647).
+ *
+ * `validate` enforces this; `help fixture` states it. Both read the constants
+ * below rather than restating them, so a change to what the verb requires
+ * cannot leave the reference describing the previous contract. The one thing
+ * this module deliberately does not own is the *page* entry's key set: a
+ * fixture page entry is a `pull` manifest entry, and `validate` reads the
+ * fields it needs rather than closing the shape, so a fixture written by a
+ * newer `pull` is not refused for carrying a field this release ignores.
+ */
+
+export const FIXTURE_MANIFEST_FILE_NAME = "manifest.fixture.json";
+export const FIXTURE_CONTRACT_VERSION = 1;
+
+/** Root fields whose absence or wrong value fails validation. */
+export const FIXTURE_REQUIRED_ROOT_FIELDS = Object.freeze([
+  "manifestVersion",
+  "siteId",
+  "pages",
+  "pagesTruncated",
+  "navigation",
+  "settings",
+  "settingsSkipped",
+  "fixture",
+]);
+
+/**
+ * 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.
+ */
+export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments"]);
+
+/** Every root field the manifest may declare. Anything else is refused. */
+export const FIXTURE_ROOT_FIELDS = Object.freeze(
+  [...FIXTURE_REQUIRED_ROOT_FIELDS, ...FIXTURE_OPTIONAL_ROOT_FIELDS].sort(),
+);
+
+/** Every field the versioned `fixture` block may declare. All are required. */
+export const FIXTURE_METADATA_FIELDS = Object.freeze(["contractVersion", "imageIds", "deliveryOrigins"]);
+
+/**
+ * Delivery origins are restricted to the reserved example domain rather than
+ * merely to HTTPS. A fixture is example data that ships and is copied; a real
+ * delivery host in one would be a live reference in every copy of it.
+ */
+export const FIXTURE_DELIVERY_ORIGIN_DOMAIN = "example.test";
+export const FIXTURE_MAXIMUM_DELIVERY_ORIGINS = 100;
+
+/** The complete example fixture this package ships. */
+export const SHIPPED_FIXTURE_NAME = "riverbend-wellness";
+
+/**
+ * The absolute path of the shipped fixture, resolved from this module rather
+ * than from the caller's directory, so it is correct for a global install as
+ * well as a checkout. `help fixture` reports it and `validate` accepts it.
+ */
+export function shippedFixtureDirectory() {
+  return fileURLToPath(new URL(`../examples/${SHIPPED_FIXTURE_NAME}/`, import.meta.url)).replace(/[\\/]$/u, "");
+}

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

@@ -412,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,
   },
@@ -425,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,
   },
@@ -507,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,