@taprootio/site-authoring 0.30.0 → 0.32.0

package/src/page-metadata.js

@@ -4,9 +4,9 @@ import { boundedByBytes } from "./session.js";
 import { displayPagePath } from "./workspace.js";
 
 /**
- * A page description is what search results and link previews show. Past about
- * 160 characters search engines cut it off, so it is warned about; past 1000 it
- * is refused, here and by the API (TR01194).
+ * Description length advice is shared with the document rules. The separate
+ * descriptionWarnings output stays compatible; the 1000-character storage
+ * maximum is still enforced here and by the API (TR01194).
  */
 export { DESCRIPTION_WARN_LENGTH };
 export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
@@ -20,27 +20,27 @@ export function requireDescriptionLength(description, field = "description") {
     throw new SiteAuthoringError(
       "pages.description_too_long",
       `The description is ${length(description)} characters; it may be at most ${DESCRIPTION_MAXIMUM_LENGTH} `
-        + `(search results show about ${DESCRIPTION_WARN_LENGTH}).`,
+        + `(the writing guidance is at most ${DESCRIPTION_WARN_LENGTH}).`,
       { field },
     );
   }
 }
 
-/** Warnings for descriptions search results will cut off, named per page. */
+/** The compatible length-warning output for known author-entered descriptions. */
 export function descriptionWarnings(pages, onProgress) {
   const items = [];
   for (const page of pages ?? []) {
-    const description = page.declaredDescription ?? page.description;
-    if (typeof description !== "string" || length(description) <= DESCRIPTION_WARN_LENGTH) continue;
+    const description = page.metadataDescriptionKnown === false ? undefined : page.declaredDescription ?? page.description;
+    if (typeof description !== "string" || length(description.trim()) <= DESCRIPTION_WARN_LENGTH) continue;
     const item = {
       code: PAGE_DESCRIPTION_LONG,
       file: page.file,
       path: displayPagePath(page.pagePath ?? page.path),
-      length: length(description),
+      length: length(description.trim()),
     };
     onProgress(
-      `Warning: ${item.file}'s description is ${item.length} characters; search results show about `
-        + `${DESCRIPTION_WARN_LENGTH}.`,
+      `Warning: ${item.file}'s description is ${item.length} characters; consider shortening it `
+        + `(guidance: at most ${DESCRIPTION_WARN_LENGTH}).`,
     );
     items.push(item);
   }

package/src/page-structure-checks.js

@@ -26,11 +26,16 @@ export const RULE_H1_DEMOTED = "seo.h1_demoted";
 export const RULE_H1_MULTIPLE = "seo.h1_multiple";
 export const RULE_HEADING_RENUMBERED = "seo.heading_renumbered";
 export const RULE_HEADING_BEFORE_TITLE = "seo.heading_before_title";
-export const RULE_IMAGE_ALT_MISSING = "a11y.image_alt_missing";
+// Image completeness is assessed from frozen library defaults during deployment.
+export const RULE_IMAGE_DEFAULT_MISSING = "a11y.image_default_missing";
 export const RULE_LINK_TEXT_EMPTY = "a11y.link_text_empty";
+export const RULE_TITLE_MISSING = "seo.title_missing";
+export const RULE_TITLE_SHORT = "seo.title_short";
 export const RULE_TITLE_LONG = "seo.title_long";
 export const RULE_DESCRIPTION_MISSING = "seo.description_missing";
+export const RULE_DESCRIPTION_SHORT = "seo.description_short";
 export const RULE_DESCRIPTION_LONG = "seo.description_long";
+export const RULE_DESCRIPTION_MATCHES_TITLE = "seo.description_matches_title";
 export const RULE_SOCIAL_IMAGE_FALLBACK = "seo.social_image_fallback";
 const RULE_ORDER = [
     RULE_H1_MISSING,
@@ -38,17 +43,42 @@ const RULE_ORDER = [
     RULE_H1_MULTIPLE,
     RULE_HEADING_RENUMBERED,
     RULE_HEADING_BEFORE_TITLE,
-    RULE_IMAGE_ALT_MISSING,
     RULE_LINK_TEXT_EMPTY,
+    RULE_TITLE_MISSING,
+    RULE_TITLE_SHORT,
     RULE_TITLE_LONG,
     RULE_DESCRIPTION_MISSING,
+    RULE_DESCRIPTION_SHORT,
     RULE_DESCRIPTION_LONG,
+    RULE_DESCRIPTION_MATCHES_TITLE,
     RULE_SOCIAL_IMAGE_FALLBACK,
 ];
-/** Search results cut a title off after about this many characters. */
-export const TITLE_WARN_LENGTH = 60;
-/** Search results cut a description off after about this many characters. */
+/** Product guidance for useful metadata, not search-engine limits. */
+export const TITLE_MINIMUM_LENGTH = 15;
+export const TITLE_WARN_LENGTH = 70;
+export const DESCRIPTION_MINIMUM_LENGTH = 50;
 export const DESCRIPTION_WARN_LENGTH = 160;
+export const METADATA_RULE_IDS = [
+    RULE_TITLE_MISSING,
+    RULE_TITLE_SHORT,
+    RULE_TITLE_LONG,
+    RULE_DESCRIPTION_MISSING,
+    RULE_DESCRIPTION_SHORT,
+    RULE_DESCRIPTION_LONG,
+    RULE_DESCRIPTION_MATCHES_TITLE,
+];
+/** Local authoring cannot resolve a home page's site settings or generated fallbacks. */
+export function localAuthoringMetadata(input) {
+    if (input.homePage)
+        return {};
+    if (input.generated) {
+        return {
+            title: input.generated.customTitle?.trim() ? input.generated.customTitle : undefined,
+            description: input.generated.customDescription?.trim() ? input.generated.customDescription : undefined,
+        };
+    }
+    return { title: input.title, description: input.description };
+}
 const MAXIMUM_DEPTH = 256;
 const MAXIMUM_SUBJECT_LENGTH = 80;
 const characters = (value) => [...value].length;
@@ -162,16 +192,6 @@ function walkBody(body) {
             case "taprootImage": {
                 imageCount++;
                 seeContent();
-                if (!nonBlank(node.attrs?.alt)) {
-                    const id = node.attrs?.imageId;
-                    findings.push({
-                        ruleId: RULE_IMAGE_ALT_MISSING,
-                        severity: "warning",
-                        subject: typeof id === "string" ? id : "",
-                        detail: "",
-                        path,
-                    });
-                }
                 return;
             }
             case "componentBlock": {
@@ -182,19 +202,10 @@ function walkBody(body) {
                 const fixedLevel = componentFixedHeadingLevel(type, data);
                 if (type === "image-banner" && imageSource(data.image)) {
                     imageCount++;
-                    if (!nonBlank(data.altText)) {
-                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
-                    }
                 }
                 // The social preview also draws on a hero's picture.
                 if (type === "hero-section" && imageSource(data.media)) {
                     imageCount++;
-                    if (!nonBlank(data.media.alt)) {
-                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
-                    }
-                }
-                if (type === "cta" && imageSource(data.mediaImage) && !nonBlank(data.mediaImage.alt)) {
-                    findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
                 }
                 if (opensPage) {
                     recordFixedHeading(outline, 1);
@@ -322,27 +333,21 @@ function collectFindings(page) {
         findings.push(...walked.findings);
         imageCount = walked.imageCount;
     }
-    if (typeof page.title === "string" && characters(page.title.trim()) > TITLE_WARN_LENGTH) {
-        findings.push({
-            ruleId: RULE_TITLE_LONG,
-            severity: "warning",
-            subject: "",
-            detail: String(characters(page.title.trim())),
-        });
-    }
-    if (typeof page.description === "string") {
-        const description = page.description.trim();
-        if (description === "") {
-            findings.push({ ruleId: RULE_DESCRIPTION_MISSING, severity: "warning", subject: "", detail: "" });
-        }
-        else if (characters(description) > DESCRIPTION_WARN_LENGTH) {
-            findings.push({
-                ruleId: RULE_DESCRIPTION_LONG,
-                severity: "warning",
-                subject: "",
-                detail: String(characters(description)),
-            });
-        }
+    const checkText = (value, minimum, maximum, missingRule, shortRule, longRule) => {
+        if (typeof value !== "string")
+            return;
+        const count = characters(value.trim());
+        const ruleId = count === 0 ? missingRule : count < minimum ? shortRule : count > maximum ? longRule : undefined;
+        if (ruleId)
+            findings.push({ ruleId, severity: "warning", subject: "", detail: count === 0 ? "" : String(count) });
+    };
+    checkText(page.title, TITLE_MINIMUM_LENGTH, TITLE_WARN_LENGTH, RULE_TITLE_MISSING, RULE_TITLE_SHORT, RULE_TITLE_LONG);
+    checkText(page.description, DESCRIPTION_MINIMUM_LENGTH, DESCRIPTION_WARN_LENGTH, RULE_DESCRIPTION_MISSING, RULE_DESCRIPTION_SHORT, RULE_DESCRIPTION_LONG);
+    const normalize = (value) => typeof value === "string" ? value.trim().replace(/\s+/gu, " ").toLowerCase() : undefined;
+    const title = normalize(page.title);
+    const description = normalize(page.description);
+    if (title && description && title === description) {
+        findings.push({ ruleId: RULE_DESCRIPTION_MATCHES_TITLE, severity: "warning", subject: "", detail: "" });
     }
     if (page.freeForm && page.hasCover === false) {
         findings.push({

package/src/presentation-reference.js

@@ -520,6 +520,14 @@ export function getAppearanceReference() {
       + "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.",
+    blockSpacingContract:
+      "Blocks on a page space themselves: text, tables and components all sit one gap apart, and the gap follows the "
+      + "site's text size. blockSpacing scales it for the whole site in both color schemes: 'standard' keeps the gap "
+      + "equal to the text spacing, 'compact' is three quarters of it and 'roomy' is one and a half times it. "
+      + "A heading's top margin scales the same way. The last text block in a padded section gets the gap as extra "
+      + "room before the section ends, and an image banner stays flush with its neighbors. A spacer block adds its "
+      + "own height to the gap, so review spacers placed by hand. A site shows the change after its next whole-site "
+      + "render.",
     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, "
@@ -841,6 +849,7 @@ export function formatPresentationReference(reference) {
       + "\nLogo contrast: " + reference.logoContrastContract
       + "\nFavicon: " + reference.faviconContract
       + "\nHeader width: " + reference.headerWidthContract
+      + "\nBlock spacing: " + reference.blockSpacingContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary
       + "\nFooter content guard: " + reference.footerContentGuard + "\n\nAtomic change set (one transaction):\n"

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 49;
+export const REFERENCE_VERSION = 51;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -695,7 +695,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "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.",
+      + "tel:+15555550123, published exactly as authored. An http or https address on another host opens in a new tab, "
+      + "and the link says so to a screen reader.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",
@@ -1018,10 +1019,14 @@ const WORKFLOW_REFERENCES = Object.freeze({
     }),
   }),
   media: Object.freeze({
-    title: "Media upload contract",
-    summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",
-    usage: `${CLI_BINARY_NAME} media upload [path...]`,
+    title: "Image defaults and media upload",
+    summary: "Read and change site-owned image defaults by ID, or upload workspace-root-relative raster files and videos.",
+    usage: `${CLI_BINARY_NAME} media images list|get|describe | media upload [path...]`,
     details: Object.freeze([
+      "media images list returns one page in images.items and images.nextPageToken; pass --page-size 1–100 (default 25) and --page-token with that exact cursor for the next page. --missing-description is a server-side filter for a null image-owned default, independent of placement alt text, captions or decorative mode. No per-result reads or page-body scans run. The authoritative default-completeness findings are in the frozen deployment report that status reads; local validate does not infer them from placement strings.",
+      "media images get <image-id> reads one library image in the selected site. Both reads expose imageId, uploadedName, defaultDescription (null when missing), descriptionRevision as a decimal string, width, height, processingState, previewUrl and responsivePreviewUrls. Preview URLs are for inspection, may expire, and are omitted from GITHUB_OUTPUT. They are not descriptions and these verbs write no workspace file.",
+      "media images describe <image-id> --description <text> --expected-revision <n> saves the default; --clear replaces --description to remove it. Supply the exact revision from list/get, including 0. --if-missing is an atomic server condition, requires nonblank text, and refuses an existing default. Conflicts report media.image_description_conflict or media.image_description_exists with exit 1; read the current image and reconcile, never retry by overwriting it blindly. Input/option errors use exit 2.",
+      "The server owns the 1000-Unicode-scalar limit: outer whitespace is trimmed, blank text becomes null, and oversized text is rejected without truncation. Descriptions may contain Unicode and newlines. The CLI preserves their text in JSON and never copies preview URLs or resolved defaults into page bodies. Site media management is required for all three verbs; profile/account/installation media are excluded. A default edit affects inherited usages at the next selected deployment; current published and in-flight snapshots keep their frozen text, while contextual overrides and decorative placements keep their choices.",
       "Paths are relative to the configured workspace root, not the shell's current directory.",
       "PNG, JPEG, GIF, and WebP are accepted. Each file uploads as its own image: a name such as logo@2x.png is only a filename, nothing pairs it with logo.png, and the platform generates the display sizes from the one file you assign (see help appearance for logos).",
       "For header logos prefer genuine transparent PNG/WebP, check contrast in both themes, and include a simplified square favicon. See help appearance for branding guidance.",
@@ -1405,6 +1410,8 @@ function decorationReference() {
     }\n## Rooted in warmth\n\nMove with confidence.\n:::`,
     maskGuidance:
       "Use a transparent PNG or WebP whose alpha channel contains only the mark. The active section context supplies the tint in both schemes.",
+    sizeGuidance:
+      "Set inlineSizePercent to size the art by the section's width, or blockSizePercent to size it by the section's height. The two cannot be combined.",
     opaqueWarning:
       "An opaque rectangle uses its whole alpha channel and will render as a tinted rectangle, not as a cut-out mark.",
   });
@@ -1449,7 +1456,7 @@ function inlineFactsReference() {
       + "mix labelled and standalone facts. An empty string is rejected, so omitting a label stays explicit. "
       + "Unicode spaces, tabs, and LF/CRLF line breaks are allowed; other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal <br> tags are rejected. The label follows the value in reading order and is outside its link.",
     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. Contact URLs require a body and refuse tel:// and mailto:// authority forms or control characters, consistently with navigation and footer links.",
+      "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. Contact URLs require a body and refuse tel:// and mailto:// authority forms or control characters, consistently with navigation and footer links. An absolute http(s) address on another site opens in a new tab with nothing to set; the site's own addresses and all other values keep the same tab.",
     markdown: Object.freeze({
       fence: INLINE_FACTS_DEFINITION.markdown.fence,
       body: INLINE_FACTS_DEFINITION.markdown.body,
@@ -1815,10 +1822,10 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "choice is per link, internal links included.",
       markdownRule:
         'Write {rel="…" target="…"} directly after the link\'s closing parenthesis: either attribute alone or both, '
-        + 'each double-quoted once. rel is space-separated; target="_blank" opens a new tab.',
+        + 'each double-quoted once. rel is space-separated; an external web address opens in a new tab on its own, target="_blank" opens a new tab for any link, and target="_self" keeps a link in the same tab.',
       pmJson:
         'In .pm.json, a link mark carries attrs.rel (a space-separated string, or null) and attrs.target ("_blank" '
-        + 'opens a new tab and publishes with noopener noreferrer added, "_self" or null keeps the same tab).',
+        + 'opens a new tab and publishes with noopener noreferrer added, "_self" keeps the same tab, and null leaves it to the default: an absolute http(s) link to another site opens in a new tab, and any other link keeps the same tab).',
       refusals:
         `Any other rel token, opener included, is refused (${CONTENT_ERROR_CODES.linkRel}); so is another target `
         + `(${CONTENT_ERROR_CODES.linkTarget}). The editor's old default, "noopener noreferrer nofollow", reads as no choice.`,
@@ -2035,9 +2042,15 @@ function formatRegistryField(field, indent = "  ") {
     : `; ${field.minScalars} through ${field.maxScalars} Unicode scalar values${
       field.nonWhitespace ? "; non-whitespace" : ""
     }`;
+  // TR01329: a field with no default key is absent until an author sets it.
+  const requirement = field.required
+    ? "required"
+    : Object.hasOwn(field, "default")
+    ? `default ${JSON.stringify(field.default)}`
+    : "optional; no default";
   const line = `${indent}${field.name.padEnd(Math.max(1, 20 - indent.length))} ${type}${
     field.nullable ? " | null" : ""
-  }; ${field.required ? "required" : `default ${JSON.stringify(field.default)}`}${bounds}${itemBounds}${scalarBounds}`;
+  }; ${requirement}${bounds}${itemBounds}${scalarBounds}`;
   return [line, ...(field.fields ?? []).map((child) => formatRegistryField(child, `${indent}  `))].join("\n");
 }
 
@@ -2124,7 +2137,7 @@ export function formatReferenceResult(result) {
       }\n  delivery URLs         ${page.sections.decoration.deliveryUrlPolicy}\n\nTint mapping:\n${
         Object.entries(page.sections.decoration.tintTokens).map(([name, token]) => `  ${name.padEnd(20)} ${token}`)
           .join("\n")
-      }\n\nTransparent-mask example:\n${page.sections.decoration.markdownExample}\n\nMask guidance: ${page.sections.decoration.maskGuidance}\nWarning: ${page.sections.decoration.opaqueWarning}\n\nRoot defaults and placement:\n${
+      }\n\nTransparent-mask example:\n${page.sections.decoration.markdownExample}\n\nMask guidance: ${page.sections.decoration.maskGuidance}\nSize guidance: ${page.sections.decoration.sizeGuidance}\nWarning: ${page.sections.decoration.opaqueWarning}\n\nRoot defaults and placement:\n${
         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(", ")

package/src/setting-reference.js

@@ -83,6 +83,15 @@ const TAPROOT_STYLES_ENTRIES = {
     "The color scheme a first-time visitor sees: light, dark, or system to follow the visitor's device.",
     "The starting scheme of every published page. A visitor who uses the theme toggle keeps their own choice.",
   ),
+  blockSpacing: entry(
+    `${BRAND} > Block spacing`,
+    "The space between blocks on every page: compact, standard or roomy. Standard keeps the gap equal to the text "
+      + "spacing; compact scales it to three quarters and roomy to one and a half times. Spacer blocks add their "
+      + "height on top.",
+    "Both color schemes, on every published page. A site shows the change after its next whole-site render, which "
+      + "happens when any settings group or navigation is selected for a stage or deploy. Pages copied forward from "
+      + "an earlier deploy keep their old spacing until then.",
+  ),
   lightLogoId: entry(
     `${BRAND} > Logo`,
     "The site-owned image used as the brand logo in the light scheme.",

package/src/settings-catalog.js

@@ -58,6 +58,7 @@ export const SETTINGS_GROUPS = Object.freeze([
       { name: "darkTheme", wireType: "theme" },
       ...stringFields(
         "defaultScheme",
+        "blockSpacing",
         "lightLogoId",
         "lightLogoUrl",
         "darkLogoId",

package/src/site-check-findings.js

@@ -2,7 +2,7 @@ import { sanitizeDiagnostic } from "./errors.js";
 import { boundedByBytes } from "./session.js";
 import rules from "./site-check-rules.json" with { type: "json" };
 import { isFormKey } from "./forms-contract.js";
-import { DESCRIPTION_WARN_LENGTH, pageStructureFindings, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
+import { DESCRIPTION_MINIMUM_LENGTH, DESCRIPTION_WARN_LENGTH, localAuthoringMetadata, METADATA_RULE_IDS, pageStructureFindings, TITLE_MINIMUM_LENGTH, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
 import { missingPageLinkFindings, normalizedPathSet } from "./site-checks.js";
 import { documentTemplate, TEMPLATE_FREE_FORM, TEMPLATE_GENERATED } from "./typed-pages.js";
 import { displayPagePath } from "./workspace.js";
@@ -51,13 +51,15 @@ export const SITE_CHECK_WORDING = Object.freeze({
   },
   "seo.heading_before_title": (finding) =>
     `has the heading '${finding.subject}' before the page's h1; it publishes as an h${finding.detail}`,
-  "a11y.image_alt_missing": () => "places an image with no alt text",
+  "a11y.image_default_missing": () => "has no default image description; set one with media images describe, then deploy",
   "a11y.link_text_empty": (finding) => `has a link to ${finding.subject} with no text`,
-  "seo.title_long": (finding) =>
-    `has a title of ${finding.detail} characters; search results show about ${TITLE_WARN_LENGTH}`,
-  "seo.description_missing": () => "has no description; search results use the start of the page instead",
-  "seo.description_long": (finding) =>
-    `has a description of ${finding.detail} characters; search results show about ${DESCRIPTION_WARN_LENGTH}`,
+  "seo.title_missing": () => "has no title; add one that identifies the page",
+  "seo.title_short": (finding) => `has a title of ${finding.detail} characters; consider a more specific title (guidance: ${TITLE_MINIMUM_LENGTH}–${TITLE_WARN_LENGTH})`,
+  "seo.title_long": (finding) => `has a title of ${finding.detail} characters; consider shortening it (guidance: ${TITLE_MINIMUM_LENGTH}–${TITLE_WARN_LENGTH})`,
+  "seo.description_missing": () => "has no description; add a short account of what the page offers",
+  "seo.description_short": (finding) => `has a description of ${finding.detail} characters; consider adding useful detail (guidance: ${DESCRIPTION_MINIMUM_LENGTH}–${DESCRIPTION_WARN_LENGTH})`,
+  "seo.description_long": (finding) => `has a description of ${finding.detail} characters; consider shortening it (guidance: ${DESCRIPTION_MINIMUM_LENGTH}–${DESCRIPTION_WARN_LENGTH})`,
+  "seo.description_matches_title": () => "has a description that repeats its title; explain what readers will find",
   "seo.social_image_fallback": (finding) =>
     finding.detail === "first_image"
       ? "has no cover image; link previews use the page's first image only when it is public and at least 1200 pixels wide"
@@ -91,15 +93,17 @@ const OFFLINE_DOCUMENT_RULES = new Set(
 function structureFindingsFor(page) {
   if (page.document === null || typeof page.document !== "object") return [];
   const template = documentTemplate(page.document);
-  // A generated page's title and description come from the site, not from an author.
-  if (template === TEMPLATE_GENERATED) return [];
   const freeForm = template === TEMPLATE_FREE_FORM;
   return pageStructureFindings(
     {
       freeForm,
       body: freeForm ? page.document : undefined,
-      title: page.title,
-      description: page.declaredDescription ?? page.description,
+      ...localAuthoringMetadata({
+        title: page.title,
+        description: page.metadataDescriptionKnown === false ? undefined : page.declaredDescription ?? page.description,
+        homePage: page.pagePath === "" || page.pagePath === "/",
+        generated: template === TEMPLATE_GENERATED ? page.document.data ?? {} : undefined,
+      }),
     },
     OFFLINE_DOCUMENT_RULES,
   );
@@ -166,6 +170,8 @@ export function evaluateOfflineSiteChecks({
     },
     siteChecks: {
       ranOffline: rulesRunningAt("validate"),
+      // Local values are checked above; only a deployment knows every effective fallback.
+      deferredToDeployment: [...METADATA_RULE_IDS],
       // Rules that need the site's own records; `taproot-site status` shows what the site finds.
       checkedBySite: SITE_CHECK_RULES.filter((rule) => !rule.runsAt.includes("validate") && rule.runsAt.includes("health"))
         .map((rule) => rule.id),
@@ -173,7 +179,7 @@ export function evaluateOfflineSiteChecks({
       checkedAtDeploy: SITE_CHECK_RULES.filter((rule) =>
         !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && rule.runsAt.includes("deploy")
       ).map((rule) => rule.id),
-      // Rules only the page editor evaluates: a cover, a description field, or a description's length (which the CLI reports as descriptionWarnings).
+      // Rules only the page editor evaluates, such as its selected cover.
       checkedInEditor: SITE_CHECK_RULES.filter((rule) =>
         !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && !rule.runsAt.includes("deploy")
         && rule.runsAt.includes("edit")

package/src/site-check-rules.json

@@ -1,10 +1,11 @@
 {
-  "version": 1,
-  "about": "The catalogue of site checks (TR01085, TR00947). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body plus cheap site lookups, 'site' rules read the site's own records, 'document' rules read only one document and its metadata, so the editor and the CLI evaluate them from shared/page-structure-checks.ts and the server does not. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health, edit (the editor, over the open document in the browser). appliesTo, when present, limits a rule to those page types. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
+  "version": 2,
+  "about": "The catalogue of site checks (TR01085, TR00947). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body plus cheap site lookups, 'site' rules read the site's own records, 'document' rules read only one document and its metadata, so the editor and the CLI evaluate them from shared/page-structure-checks.ts and the generator compiles deployment advice from the same pure evaluator. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health, edit (the editor, over the open document in the browser). appliesTo, when present, limits a rule to those page types. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
   "runPoints": ["save", "validate", "deploy", "health", "edit"],
   "rules": [
     { "id": "link.page_missing", "severity": "warning", "scope": "page", "runsAt": ["save", "validate", "health"], "subject": "page_path", "detail": "none" },
     { "id": "image.missing", "severity": "warning", "scope": "page", "runsAt": ["save", "health"], "subject": "image_id", "detail": "none" },
+    { "id": "a11y.image_default_missing", "severity": "warning", "scope": "site", "runsAt": ["deploy", "health"], "subject": "image_id", "detail": "none" },
     { "id": "form.none_chosen", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "none", "detail": "none" },
     { "id": "form.unreadable", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_reference_text", "detail": "none" },
     { "id": "form.missing", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_id", "detail": "none" },
@@ -24,11 +25,14 @@
     { "id": "seo.h1_multiple", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "h1_claimant" },
     { "id": "seo.heading_renumbered", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "authored_and_published_level" },
     { "id": "seo.heading_before_title", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "published_level" },
-    { "id": "a11y.image_alt_missing", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "image_id", "detail": "none" },
     { "id": "a11y.link_text_empty", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "link_target", "detail": "none" },
-    { "id": "seo.title_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "character_count" },
-    { "id": "seo.description_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "none" },
-    { "id": "seo.description_long", "severity": "warning", "scope": "document", "runsAt": ["edit"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.title_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
+    { "id": "seo.title_short", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.title_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
+    { "id": "seo.description_short", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_matches_title", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
     { "id": "seo.social_image_fallback", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["edit"], "subject": "none", "detail": "social_image_source" }
   ]
 }

package/src/typed-pages.js

@@ -1,6 +1,8 @@
 import { FREE_FORM_TEMPLATE_VERSION, TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { isVideoEmbedId } from "./content/video-embed-url.js";
 import { SiteAuthoringError } from "./errors.js";
+import { isImageDescriptionMode } from "./content/image-description-validation.js";
+import { stripImageDescriptionHydration } from "./content/image-description-document.js";
 import { requireDescriptionLength } from "./page-metadata.js";
 
 /**
@@ -323,7 +325,7 @@ const RECIPE_KEYS = [
   "cookingMethod",
 ];
 const ALBUM_KEYS = ["introductionBody", "images", "seamless", "borderWidth", "place"];
-const ALBUM_IMAGE_KEYS = ["imageId", "caption", "width", "height"];
+const ALBUM_IMAGE_KEYS = ["imageId", "caption", "width", "height", "altText", "descriptionMode"];
 const ALBUM_MAXIMUM_BORDER_WIDTH = 20;
 const MAXIMUM_MINUTES = 100_000;
 const MAXIMUM_SERVINGS = 10_000;
@@ -372,12 +374,17 @@ const DATA_BUILDERS = Object.freeze({
       ["introductionBody", raw.introductionBody],
       [
         "images",
-        raw.images.map((image) => ({
-          imageId: image.imageId,
-          caption: image.caption ?? "",
-          width: image.width ?? 0,
-          height: image.height ?? 0,
-        })),
+        raw.images.map((image) => {
+          const authored = stripImageDescriptionHydration(image);
+          return definedEntries([
+            ["imageId", authored.imageId],
+            ["caption", authored.caption ?? ""],
+            ["width", authored.width ?? 0],
+            ["height", authored.height ?? 0],
+            ["altText", authored.altText],
+            ["descriptionMode", authored.descriptionMode],
+          ]);
+        }),
       ],
       ["seamless", raw.seamless],
       ["borderWidth", raw.borderWidth],
@@ -486,6 +493,14 @@ function canonicalSourceData(template, data, file) {
       requireKeys(image, ALBUM_IMAGE_KEYS, file, at);
       requireIdentifier(image.imageId, file, `${at}.imageId`);
       if (image.caption !== undefined) requireString(image.caption, file, `${at}.caption`);
+      if (!isImageDescriptionMode(image.descriptionMode)) {
+        throw fail(
+          "pages.document_shape",
+          `'${file}' ${at}.descriptionMode must be inherit, custom or decorative.`,
+          `${file}:${at}.descriptionMode`,
+        );
+      }
+      if (image.altText !== undefined && image.altText !== null) requireString(image.altText, file, `${at}.altText`);
       if (image.width !== undefined) requireCount(image.width, file, `${at}.width`, 100_000);
       if (image.height !== undefined) requireCount(image.height, file, `${at}.height`, 100_000);
     });
@@ -684,8 +699,9 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   if (name === undefined) return undefined;
   const raw = template[PAGE_TEMPLATES[name].dataKey];
   if (!isPlainObject(raw)) return undefined;
-  if (name === TEMPLATE_FREE_FORM) return isPlainObject(raw.body) ? raw.body : undefined;
-  const data = PAGE_PROJECTIONS[name](raw);
+  const authored = stripImageDescriptionHydration(raw);
+  if (name === TEMPLATE_FREE_FORM) return isPlainObject(authored.body) ? authored.body : undefined;
+  const data = PAGE_PROJECTIONS[name](authored);
   if (data === undefined) return undefined;
   // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
   const generated = name === TEMPLATE_GENERATED || name === TEMPLATE_LEGAL;

package/src/verbs/deploy.js

@@ -1,3 +1,4 @@
+import { describeNavigationReadiness, isNavigationReady, reportNavigationReadiness } from "../navigation-readiness.js";
 import {
   DEPLOYMENT_ENVIRONMENT_PRODUCTION,
   DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -154,6 +155,7 @@ function reportReadiness(readiness) {
   const blockers = boundedList(readiness.blockers, MAXIMUM_REPORTED_BLOCKERS);
   return {
     state: readiness.state,
+    navigationReadiness: reportNavigationReadiness(readiness.navigationReadiness),
     approvedPageCount: readiness.approvedPageCount,
     selectedPageCount: readiness.selectedPageCount,
     blockedPageCount: readiness.blockedPageCount,
@@ -350,6 +352,15 @@ export async function deploy(invocation) {
       // The estimate must recognize the request it is about to be followed by.
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
+    onProgress(describeNavigationReadiness(readiness.navigationReadiness));
+    if (!isNavigationReady(readiness.navigationReadiness)) {
+      const media = readiness.blockers.length ? ` This candidate also has ${readiness.blockers.length} media blocker(s).` : "";
+      throw new SiteAuthoringError(
+        "deploy.navigation_blocked",
+        describeNavigationReadiness(readiness.navigationReadiness) + media,
+        { field: "Navigation", status: readiness.navigationReadiness.state },
+      );
+    }
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
         "deploy.media_blocked",

package/src/verbs/index.js

@@ -17,6 +17,9 @@ import {
   VERB_MARKETING_PULL,
   VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
+  VERB_MEDIA_IMAGES_LIST,
+  VERB_MEDIA_IMAGES_GET,
+  VERB_MEDIA_IMAGES_DESCRIBE,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
   VERB_PAGES_META_SET,
@@ -58,6 +61,7 @@ import { logout } from "./logout.js";
 import { marketingPull } from "./marketing-pull.js";
 import { marketingPush } from "./marketing-push.js";
 import { mediaUpload } from "./media-upload.js";
+import { mediaImagesDescribe, mediaImagesGet, mediaImagesList } from "./media-images.js";
 import { navPush } from "./nav-push.js";
 import { pagesDelete } from "./pages-delete.js";
 import { pagesMetaSet } from "./pages-meta-set.js";
@@ -118,6 +122,9 @@ import { whoami } from "./whoami.js";
  * ```
  * {
  *   fixturePath,   // validate: one offline authoring-fixture directory
+ *   imageId,       // media images get/describe: site-owned library image UUID
+ *   pageSize, pageToken, missingDescription, // media images list
+ *   imageDescription, clearDescription, expectedRevision, onlyIfMissing, // media images describe
  *   paths,         // media upload: files and/or directories to upload;
  *                  //   with none, the workspace's media/ directory is walked
  *   formKeys,      // forms validate / push: narrow to these form keys;
@@ -187,6 +194,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_MARKETING_PUSH]: marketingPush,
   [VERB_LINK_BUILD]: linkBuild,
   [VERB_MEDIA_UPLOAD]: mediaUpload,
+  [VERB_MEDIA_IMAGES_LIST]: mediaImagesList,
+  [VERB_MEDIA_IMAGES_GET]: mediaImagesGet,
+  [VERB_MEDIA_IMAGES_DESCRIBE]: mediaImagesDescribe,
   [VERB_APPROVE]: approve,
   [VERB_DEPLOY]: deploy,
   [VERB_PREVIEW_PAGE]: previewPage,